RESTful API Resources

Dmitri Dolguikh dmitri at redhat.com
Thu Nov 8 12:45:06 UTC 2012


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




More information about the aeolus-devel mailing list