[rest-practices] rest-practices purpose
Bryan Kearney
bkearney at redhat.com
Wed Apr 28 12:43:07 UTC 2010
On 04/27/2010 04:06 PM, Mark McLoughlin wrote:
> On Fri, 2010-04-23 at 10:32 -0400, Perry Myers wrote:
>
>> For cloud related efforts, we want to make sure that all of our usages of
>> REST are consistent wrt style/best practices. Ideally, it would be best
>> if all Red Hat REST usage is on the same page. But barring that, the
>> cloud usage should at least be consistent.
>>
>> So bburke's REST pages are certainly a good starting poing wrt
>> style/usage. But Mark M. will also be maintaining a separate wiki page
>> (he'll provide the link) that is specific to cloud usage of REST.
>> Hopefully it won't duplicate all of the good work that bburke has done,
>> but instead will just point out style differences between his pages and
>> what cloud folks agree on.
>>
>> It will be expected that all cloud developers will conform to the style as
>> agreed upon in Mark's wiki page.
>
> Okay, I've taken a very rough first cut at this:
>
> http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide
>
> Please feel free to edit or discuss here. Everything is still open for
> discussion. Please do try and keep topics in separate threads so that we
> can easily reference the discussion from the wiki.
Great first cut! Comments below
Intro
I will stop harping on this. But I like the idea of "levels" of the API
based on the number of principals which you achieve.
Guidelines
- In XML: Can we assume all elements? This effects how we marshal to JSON.
- In urls, should query paramaters be puthon styled? Also. .I assume we
use query parameters not form parameters.
- Another item to discuss would be return codes, and how to handle error
messages. For example, we are using a specific http return code for
error types. We do not have sub messages, but we put a localized message
into a json blob in the body of the message which is returned. It would
be nice to standardize on that message, and the use of return codes.
- Also, on return codes, it would be nice to standardize on the return
codes. So.. should Creates (POST to FOO) return the new object and not a
204? Should deletes return a 204?
- Another discussion we have had is on how to handle object graphs. Lets
assume we have a resource model which is "Company -> Department ->
Employee". We have assumed the API would start at a resource and "go
down". So, in this case the following apis could be supported:
companies/{company_uuid}/departments/{dept_uuid}/employees/{emp_id}
departments/{dept_uuid}/employees/{emp_id}
However, we would not support
departments/{dept_uuid}/company
- I assume urls and xml collections are plural resource names <departments>
- Finally, the last thing we discussed was how does security fit in with
collections. We have assumed that if user 1 calls
companies/{company_uuid}/departments
they may see a different collection from user 2 based on their roles and
permissions.
-- bk
More information about the rest-practices
mailing list