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