Forward (http://getfwd.com) employs conventions like this between the template and model layers of an MVC style framework.
get("/accounts") // collection
get("/accounts", [limit => 10, page => 3]) // pagination
get("/accounts/email@address.com") // single record
get("/accounts/email@address.com/orders") // relations
get("/accounts/email@address.com/orders/10234/items/6/price") // deep relations
get("/accounts", [search => "john"]) // search
get("/accounts", [fields => "name, email"]) // partials
get("/accounts", [order => "name desc"]) // sorting
get("/accounts", [login => [...]]) // special conventions
post("/accounts", [alternate_email => $alt, ":validate" => [required => [alternate_email]]) // validation
put(...) // pretty much what you expect
delete(...) // same
The interesting thing about moving REST conventions to the model layer, is that you can suddenly create external facing APIs in various formats really easily. I'm hoping/expecting this will become a more common pattern.
I love that I've learned most of these best practices already because I use Rails. A good technology (or framework) teaches people how to do something better.
Get rid of the .json, use a specific media type, if at all possible refer to a schema description in the metadata presented.
Search is a service, not a part of a resource. Whether a seperate search service aggregating all different REST resources is supplied or not is irrelevant in the example case as resource collections can be filtered, which the article highlights (the colour= parameter), for a dogs resource, or a phonebook resource etc. filtering on attributes (which can use wildcards or regexes as seen fit to do so) provides the necessary functionality anyway. Search is a diversion in these cases.
I agree with going versionless (though I can see the case for it also depending on how the API is intended to be used).
Get rid of .json? Make it optional sure, but allow it if the client wants to be specific. Seems like a good feature in that sense (optional with a good default).
I agree that search should not be a resource, but perhaps a parameter for filtering in addition to explicitly named param filters.
Does anyone else find the dual role of POST as a create verb and as "complex search criteria" verb problematic? The WebDav RFC defines a SEARCH verb; why don't we see it used in more REST HTTP APIs?
This is a nice presentation about URL best practices, but it doesn't really get into the most relevant or interesting topic of RESTful API design which is resource design representation. I'd love to see more in these specific areas with concrete examples of the approach others have taken.
8 comments
[ 3.6 ms ] story [ 24.5 ms ] threadColour me unconvinced! I don't really see how promoting this hacky form of REST moves us forward.
Search is a service, not a part of a resource. Whether a seperate search service aggregating all different REST resources is supplied or not is irrelevant in the example case as resource collections can be filtered, which the article highlights (the colour= parameter), for a dogs resource, or a phonebook resource etc. filtering on attributes (which can use wildcards or regexes as seen fit to do so) provides the necessary functionality anyway. Search is a diversion in these cases.
Go versionless.
Get rid of .json? Make it optional sure, but allow it if the client wants to be specific. Seems like a good feature in that sense (optional with a good default).
I agree that search should not be a resource, but perhaps a parameter for filtering in addition to explicitly named param filters.
Thanks for sharing your thoughts on it.