6 ms·

Teach a Dog to REST

33 points by tomse 14y ago

ericingram 14y ago
Forward (http://getfwd.com 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.
mattangriffel 14y ago
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.
3amOpsGuy 14y ago
.json in the resource identifier? "Verbs are bad", except when it's "search"? /v1/dogs/molly vs. /v2/dogs/molly ? Colour me unconvinced! I don't really see how promoting this hacky form of REST moves us forward.
- ericingram 14y ago
  What do you propose as alternative to these issues?
  - 3amOpsGuy 14y ago
    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. Go versionless.
    - ericingram 14y ago
      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. Thanks for sharing your thoughts on it.
politician 14y ago
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?
nwp 14y ago
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.

33 points by tomse 14y ago

Forward (http://getfwd.com 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.

mattangriffel 14y ago

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.

3amOpsGuy 14y ago

.json in the resource identifier? "Verbs are bad", except when it's "search"? /v1/dogs/molly vs. /v2/dogs/molly ? Colour me unconvinced! I don't really see how promoting this hacky form of REST moves us forward.

ericingram 14y ago
What do you propose as alternative to these issues?
- 3amOpsGuy 14y ago
  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. Go versionless.
  - ericingram 14y ago
    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. Thanks for sharing your thoughts on it.

politician 14y ago

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?

nwp 14y ago

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.