On Wed, 2012-11-07 at 09:43 +0100, Martyn Taylor wrote: > As promised in yesterdays session, here is the REST guide written by > Geert Jansen. I've found this particularly useful it's well worth a read: > > https://restful-api-design.readthedocs.org/en/latest/
This is an excellent resource - though I violently disagree with one of the points made in there: custom content types. Unless it's reasonable to expect that clients will use URL's into your API without any other context, it's enough to indicate the format of the serialization in the content type (less fancy: stick to application/xml and application/json) If you absolutely have to, you can also encode semantic information about the representation with media type parameters[1] (Content-Type: application/xml; entity=fancy-resource) Lots of fine-grained content types become a big hassle for clients, since they need to set the Accept header just right to select the JSON or XML representation. > Also worth looking over is the HTTP specification: Since our API is REST > over HTTP (which means sticking to the letter of the law of HTTP). > > Lastly, It's well worth taking a look at Roy Fielding thesis chapter > where he outlines REST. I don't have a link but should be easily > "googlable". I also recommend the rest-practices guide[2] that we put together quite a while ago; might be worth sticking updates in there. Also, I'd like to pimp what I wrote around evolution of REST API's[3] - this was mostly for a discussion around versioning of REST API's, but might be useful in other contexts, too. David [1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7 [2] http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide [3] http://watzmann.net/blog/2012/08/rest-api-evolution.html
