On 08/11/12 02:27 PM, Martyn Taylor wrote:
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).
or, going a bit farther:
<instance>
<state href="instances/1111/state">
<value>REBOOTING</value>
<actions>
<link rel="next" href="instances/1111/state/next">
this way the xml for expressing of available operations will be
consistent across all resources. Alternatively, the state could be
changed by PUTting one of the available states into the 'state' field of
the 'instance' resource.
State itself could either be a child resource of 'instance' if it's
'instance'-specific, or a root-level resource otherwise.
-d
[3] http://watzmann.net/blog/2012/08/rest-api-evolution.html
