[rest-practices] rest-practices purpose

[Bill Burke]

Bryan Kearney wrote:
> 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.
> 

You really need to rename the "actions" section to "Modeling 
Operations".  Modeling operations, as we've already discussed, is about 
the most difficult thing to understand and get right with REST.

-- 
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com