What does the JSON version of that resource look like? -steve
On Nov 8, 2012, at 9:20 AM, Dmitri Dolguikh <[email protected]> wrote: > 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 >>> >>> >> >> >
