[rest-practices] rest-practices purpose
Mark McLoughlin
markmc at redhat.com
Wed Apr 28 16:27:48 UTC 2010
On Wed, 2010-04-28 at 08:43 -0400, 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
Thanks
> 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.
Good idea. I suggest two levels - "sucky" and "not sucky"
(Sorry, couldn't resist :-)
I do like the idea, in general - it's a way of saying "I'm 95% RESTful,
get off my back about the other 5%"
Specifically with our APIs, though, I'm think we should strive for
HATEOAS
> Guidelines
> - In XML: Can we assume all elements? This effects how we marshal to JSON.
The perennial XML debate ...
And example I'm looking at right now:
<storage type="nfs">
<host>...</host>
<storage>...</storage>
</storage>
makes more sense to me than:
<storage>
<type>nfs</type>
<host>...</host>
<storage>...</storage>
</storage>
same for e.g.:
<vm id="..." name="..." href=".../>
I honestly don't have any strong opinions on the matter though.
DV - any thoughts on this?
> - In urls, should query paramaters be puthon styled?
As opposed to alllowercase? I guess so, yeah
> Also. .I assume we use query parameters not form parameters.
You mean include the query parameters in the URL instead of POSTing
application/x-www-form-urlencoded ?
Yes, I think that makes sense, except where the target *only* takes
query parameters - e.g. application/x-www-form-urlencoded might be a
valid resource representation for the likes of action resources, but
that's separate, I guess
> - 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?
Yeah, this is important stuff to cover. Feel free to to flesh out the
guide on these and start a thread. We haven't started thinking about it
much for rhevm-api yet
> - 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
Nice topic - could you kick off a separate thread on this? I was just
hitting a similar question
> - I assume urls and xml collections are plural resource names <departments>
Yep, added
> - 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.
Yep, that goes for e.g. actions too - I've added the start of a security
section with this
Cheers,
Mark.
More information about the rest-practices
mailing list