RESTful API Resources

Martyn Taylor mtaylor at redhat.com
Thu Nov 8 14:27:56 UTC 2012


On 11/07/2012 07: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)
I agree custom contents types are not a good idea.  The parameter media 
type solution sounds like a reaosnable approach, that avoids defining 
custom types.
>
> 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
This is also a nice guide.  However, I do disagree with the example that 
is shown in the links section, and since we just spoke about something 
similar I will address this now before others bring it up.  So the guide 
uses the following example:

<actions>
   <link rel="reboot" href="/vms/1234/reboot"/>
   <link rel="shutdown" href="/vms/1234/shutdown"/>
</actions>

I think that representing method calls in this way (as resources) is 
against the spirit of REST and in my opinion violates the "Unified 
Interface" constraint.  Instead of representing action resources we 
should think about changing the state the resource.  For example, this 
could be better represented as current state.  e.g.

<instance>
   <state>
     <value>REBOOTING</value>
     <next_states>
       <state href="instaces/states/1>
....

This way we would simply update the resource with a different state 
(chosen from the next states list).

> [3] http://watzmann.net/blog/2012/08/rest-api-evolution.html
>
>





More information about the aeolus-devel mailing list