

Teach a Dog to REST - tomse
http://blog.apigee.com/detail/restful_api_design/

======
ericingram
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.

------
politician
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?

------
mattangriffel
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.

------
nwp
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.

------
3amOpsGuy
.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
What do you propose as alternative to these issues?

~~~
3amOpsGuy
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
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.

