On 07/11/12 06:53 PM, David Lutterkort wrote:
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.
Any opinion on versioning via mime-types, ie: Content-Type:
application/xml; version=1.0?
This results in non-versioned resource urls, which IMHO is beneficial.
-d
> 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