I would appreciate y'all talking a look at it, as the goal is to evangelize these conventions to the larger community, to encourage interoperability. In particular, let me know if you have links to other relevant resources and/or efforts.
Nice guide! It’s clear, concise and definitely useful.
One important technical detail needs mention, and that is emulating PUT and DELETE over POST with the “_method” parameter. Current web browsers should be able to consume REST resources. This may be a hackish little detail, but don’t forget that you’re trying to define a common interface here to “ensure interoperability”.
While you’re talking about HTTP methods you should also mention common HTTP responses with REST other than common 200 or 404. They’re defined in the HTTP spec, but listing them for informative reasons wouldn’t hurt.
This sentence should be rephrased: “Note that most browsers do not currently support PUT and DELETE, so
those need to be implemented using a POST with an “?_method=” argument.”
It should say:
“Since most browsers do not currently support PUT and DELETE, those methods have to emulated over POST by providing a “_method” parameter with a value of “PUT” and “DELETE”, respectively.”
Don't forget the 422 Unprocessable Entity status code. You'd use
it when the request is syntactically valid, but still contains
invalid information. An example of this would be if someone sent
an valid XML document, but one of the elements contained data that
didn't meet the validates_* constraints in a model.
I usually reserve 400 Bad Request for the most generic of errors
not covered by any other 4xx status codes, which is fairly rarely
in practice.
Please let me know if there's anything else, especially links to
additional relevant resources.
How about mentioning conventions for searching using query strings
that I've seen in ActiveResource? Any extra params you send through
to the find() method are added to the query string. Here's an article
exploring different conventions for search:
I would appreciate y'all talking a look at it, as the goal is to
evangelize these conventions to the larger community, to encourage
interoperability. In particular, let me know if you have links to
other relevant resources and/or efforts.
Ernie,
Is there a restful convention for creating or changing association attributes that relates resources to each other?
For example I have a series of Activities each of which can cover many Subjects and Subjects can have many Activities. I can find scoped collections using nested resources. If:
/subjects/5 => biology
Then
/subjects/5/activities
Will return all the activities that cover the subject biology.
Now I'd like to add the subject biology to activity 18 but I don't need to update any other part of the activity resource. It might be clear in a RESTful way to do this:
/subjects/5/activities/18/belongs_to
A more natural language url form might look like this:
/activities/18/belongs_to/subjects/5
Of course since Activities can have many Subjects and Subjects can have many Activities then there is either a join table to connect the two models or a richer has_many :through table. A plain join table has no resource manifestation other than the relationship between the two resources -- the records in the join table have no ids that refer to them specifically.
Don't forget the 422 Unprocessable Entity status code. You'd use
it when the request is syntactically valid, but still contains
invalid information. An example of this would be if someone sent
an valid XML document, but one of the elements contained data that
didn't meet the validates_* constraints in a model.
How about mentioning conventions for searching using query strings
that I've seen in ActiveResource? Any extra params you send through
to the find() method are added to the query string. Here's an article
exploring different conventions for search:
That's a great suggestion, but right know there doesn't seem to be any "standard" for how to do it. Many if resource_search gets standardized (and integrated into Rails) then we can make *that* the convention...
If you follow the discussion linked to from this ticket you'll see a
post from Roy Fielding, where he suggests 422 as sufficient for the
purposes of reporting that the request body was syntactically valid,
but semantically invalid -- that the server is unable to process it.
Prior to Roy's post people were talking about creating a 418 Invalid
status code, until he pointed out the previously defined 422.
How about mentioning conventions for searching using query strings
that I've seen in ActiveResource? Any extra params you send through
to the find() method are added to the query string. Here's an article
exploring different conventions for search:
That's a great suggestion, but right know there doesn't seem to be
any "standard" for how to do it. Many if resource_search gets
standardized (and integrated into Rails) then we can make *that* the
convention...
It sort of is a convention right now in ActiveResource, although not all
Rails apps make use of it. In the docs [1] for ActiveResource#find it
shows the following example:
Personally, for search, I find that
/people.xml?q=a_ferret_compatible_query_or_similar is nicer than the
above, and more flexible, in general. Yes it's RPCish, but this is
one of those times where loosening the metaphorical bolt is warranted,
I think.
Also, what's the best practice w.r.t. URL nesting for polymorphic
resources? We try to limit ourselves to not nesting more than
2-levels deep (e.g., /posts/1/comments is 2-level deep). One
additional level is OK as long as it's due to a namespace. So
/admin/posts/1/comments is ok. What do you think?