RESTful API Resources

Dmitri Dolguikh dmitri at redhat.com
Fri Nov 9 08:30:55 UTC 2012


On 08/11/12 04:00 PM, Steve Loranz wrote:
> What does the JSON version of that resource look like?
pls. see below.

>
> -steve
>
>
> On Nov 8, 2012, at 9:20 AM, Dmitri Dolguikh <dmitri at redhat.com> 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

or, the same in json:
"instance": {
   "state" : {
     "href" : "instances/1111/state",
     "value": "REBOOTING"
     "actions" : [{"link" : { "rel" : "next", "href" : 
"instances/1111/state/next" }}]

-d



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




More information about the aeolus-devel mailing list