On 08/04/2011 01:10 AM, Geert Jansen wrote:
Hi,
i wanted to do this for a long time, and finally got it it. See the link
below for an essay on RESTful API design, based on lessons learnt from
rhevm-api project:
http://readthedocs.org/docs/restful-api-design/en/latest/
From the intro: "This is essay is an attempt to put down my thoughts on
how to design a real-world yet beautiful RESTful API." It goes into such
topics as JSON vs XML, why not XMLSchema, creating CLIs, and more.
Mark, it also contains a worked out version of your idea to use forms
for describing inputs.
Feedback is welcome!
Excellent write up, thanks Geert!
A couple of thoughts:
- As a fan of JSON I'm glad to read what you wrote about it. But tbh I
think the problems described with XML were long ago solved in XMLRPC
(http://www.xmlrpc.com/spec). But I always felt XML was too "big" for
this. JSON in the other side has a smaller scope that suits perfectly
this use case, saves the developer the nuisance of parsing XML and the
best of all it greatly integrates with modern HTML apps. Looking forward
to see JSON support in the RHEV API completed :-)
(https://bugzilla.redhat.com/show_bug.cgi?id=652883 ,
https://fedorahosted.org/rhevm-api/ticket/192)
Have to say as a former XMLRPC fan, it brought a simple standard way of
client-server communication over HTTP, sadly it wasn't broadly adopted
in the end.
- Talking about HTML apps, I think all RESt APIs should implement CORS!
(https://fedorahosted.org/rhevm-api/ticket/195). Its my little unheard
crusade ;-)
- The HTML format part maybe could incorporate something like "use
nested <table> tags for representing the subcollections of a resource",
but would be still a bit oversimplified.
I specially like the effort made in Deltacloud around the "HTML format".
It's of great help when coding a real client. Talking about Deltacloud,
it's JSON implementation is great, maybe only missing POST JSON strings
to be complete (currently requires POST strings to be in urlencode format).
- At the "URL structure" chapter, when said "Even though sub-collections
may be arbitrarily nested, in my experience, you want to keep the depth
limited to 2, if possible." Why not talk about the problem in REST when
you need to retrieve resources and also some of its subcollections,
which could generate way too many HTTP calls. I like the solution Eoghan
brought with "detail" param.
- "URL Templates", many REST implementations I've seen exploit GET
params in deep. I was I bit surprised when we didn't in the RHEV API.
Although I agree that abusing GET params tend to lead to confusion and
less cleaner clients.
- "Ranges / Pagination", I think the options here should be richer, only
from X to Y is not going to solve all the needs for paging IMO.
- "Notifications", the "long polling" idea is cool!
- "Forms", the idea remembers me to WAP (the restricted HTML for old
mobile devices) and its WML <inputs> definition
(http://www.tutorialspoint.com/wml/wml_inputs.htm). Specially the format
attrib of <input>'s was an original idea IMHO, something like simplified
regex.
Regards,
Tomas
PD. CCing deltacloud-dev as well.
