rest api reading

Robert Buck rbuck at redhat.com
Sat Nov 5 11:52:26 UTC 2011


On 11/04/2011 07:27 PM, Charles Crouch wrote:
> I thought I'd shared this already but I can't find it in my history...
>
> Some thoughts from the oVirt.org team on rest apis
>
> http://readthedocs.org/docs/restful-api-design/en/latest/
>
> Bob, Heiko thoughts?
>
> Cheers
> Charles
> _______________________________________________
> rhq-devel mailing list
> rhq-devel at lists.fedorahosted.org
> https://fedorahosted.org/mailman/listinfo/rhq-devel
Thanks, Charles. I read the article, and will make another pass through 
it. Here are some initial comments...

It's a large article, and I agree with lots of points, below I will 
number the big points I tend to disagree with. By pointing out several 
things I disagree, by no means does this suggest I invalidate the 
authors exploration of REST. This is a work in progress.

I find going back to the industry experts and source material most 
beneficial...

*  The video here provides a good introduction from an expert:  
http://www.infoq.com/interviews/steve-vinoski-erlang-rest#

*  And Fielding's dissertation is here:  
http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

Here are some thoughts regarding the article itself:

1. The link, 
http://readthedocs.org/docs/restful-api-design/en/latest/methods.html, 
falls into the trap so many others do, that people often reduce 
POST/GET/PUT/DELETE to CRUD, and this is a fundamental mistake. When 
deciding whether to use PUT or POST, e.g., the deciding factor is 
whether the caller KNOWS a priori the address of the created resource. 
If they do they MUST use PUT, otherwise use POST. Generally, if the 
caller knows the resource address a priori, this OFTEN means that the 
call is idempotent, using POST makes no sense then. PUT is idempotent, 
not POST.

2. In the link, 
http://readthedocs.org/docs/restful-api-design/en/latest/methods.html, 
the author misunderstands the Range header completely. Support is only 
provided for byte offsets by spec, and to extend the meaning of the HTTP 
spec is a fundamental violation to open standards. Fielding makes this 
very clear.

3. The links, 
http://readthedocs.org/docs/restful-api-design/en/latest/methods.html, 
and http://readthedocs.org/docs/restful-api-design/en/latest/urls.html, 
place heavy emphasis on collection oriented APIs. This is a trap that 
developers frequently fall into with REST. Yes, understanding the 
structure of the resource representation is one part, but what REST is 
really about are guided choices, self-descriptive work-flows using 
standard schemes like HTML and Atom Pub. It should enable guided 
discovery. Let me provide a concrete example in RHQ. In RHQ there are at 
least two different models we would need to address: collection-based 
largely append-only, and work-flow based largely ad-hoc explorative. An 
example of the former may be metrics, an example of the latter would be 
operations. In the former the caller can inquire which collections are 
available, what OPTION are available on each collection, and then page 
through each, or perhaps append to them. With the latter the user will 
inquire what operations are available on a resource then they will be 
guided through a workflow on a specific action they want to perform; at 
each step along the way they will be presented with CHOICES and for each 
choice a related address and required input fields.

4. The note on URL structure here, 
http://readthedocs.org/docs/restful-api-design/en/latest/urls.html... to 
suggest guidelines is "okay", but an implementer of the REST API needs 
to start elsewhere, understanding their system, the media types, 
representations, processes, operations, etc. You MAY choose an alternate 
approach, for example for operations.

5. The relative vs absolute argument here, 
http://readthedocs.org/docs/restful-api-design/en/latest/urls.html, I 
don't agree with. Look at HTML, resources MAY OPTIONALLY be relative. 
There's nothing wrong with that.

6. The actions comment here, 
http://readthedocs.org/docs/restful-api-design/en/latest/methods.html, 
violates lots of what Fielding was asserting in his dissertation. 
Relations address this need, and this fits well into Atom Pub. Encoding 
actions into URI is seen as evil, it is evil. A URI represents the 
immutable identity for a resource, not behaviors; does its identity 
change if you tack on an action, as in "&action=get". By no means, no. 
Behavior and identity are orthogonal concerns.

-Bob


More information about the rhq-devel mailing list