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!
Regards, Geert
If it were appropriate I'd hump your leg. Please, everyone, even if you don't feel the need to build an api that honours the intent of REST, at least read this and understand what one looks like. 99% of so-called REST APIs are really just HTTP APIs (which is sad as REST has very little to do with HTTP). Single point of entry, linking via opaque links, and media-types - 3 of the most fundamental aspects of REST and yet 3 of the most ignored. Yes I'm looking at you Ruby on Rails.
Nice work.
On 04/08/2011, at 9: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!
Regards, Geert _______________________________________________ aeolus-devel mailing list aeolus-devel@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/aeolus-devel
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.
Geert--
This is geat work, and will definitely serve everyone well to have as a common document, since there's a lot of people flailing around with REST. I really appreciated your opions/justifications, such as those regarding Link: headers. The emphasis on non-XML is also quite refreshing. Seeing YAML is super. :)
Thanks for putting this together.
-Bob
On Aug 3, 2011, at 7:10 PM, 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!
Regards, Geert
rest-practices mailing list rest-practices@redhat.com https://www.redhat.com/mailman/listinfo/rest-practices
I like it. We should try and link it into the REST-* web site too.
Bill, what do you think?
Mark.
On 4 Aug 2011, at 00:10, 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!
Regards, Geert
rest-practices mailing list rest-practices@redhat.com https://www.redhat.com/mailman/listinfo/rest-practices
--- Mark Little mlittle@redhat.com
JBoss, by Red Hat Registered Address: Red Hat UK Ltd, Amberley Place, 107-111 Peascod Street, Windsor, Berkshire, SI4 1TE, United Kingdom. Registered in UK and Wales under Company Registration No. 3798903 Directors: Michael Cunningham (USA), Charlie Peters (USA), Matt Parsons (USA) and Brendan Lane (Ireland).
sounds good.
On 8/9/11 8:06 AM, Mark Little wrote:
I like it. We should try and link it into the REST-* web site too.
Bill, what do you think?
Mark.
On 4 Aug 2011, at 00:10, 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!
Regards, Geert
rest-practices mailing list rest-practices@redhat.com https://www.redhat.com/mailman/listinfo/rest-practices
Mark Little mlittle@redhat.com
JBoss, by Red Hat Registered Address: Red Hat UK Ltd, Amberley Place, 107-111 Peascod Street, Windsor, Berkshire, SI4 1TE, United Kingdom. Registered in UK and Wales under Company Registration No. 3798903 Directors: Michael Cunningham (USA), Charlie Peters (USA), Matt Parsons (USA) and Brendan Lane (Ireland).
Hi Geert-
Awesome piece, thanks a lot for writing it up! I think this is sorely needed and we'll try to pattern FataMorgana after it as much as we can.
I have a couple remarks/questions/suggestions/caveats, though, see attached annotated PDF. Let me know what you think—we can also take it offline.
-Tobias
On Aug 9, 2011, at 05:06 , Mark Little wrote:
I like it. We should try and link it into the REST-* web site too.
Bill, what do you think?
Mark.
On 4 Aug 2011, at 00:10, 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!
Regards, Geert
rest-practices mailing list rest-practices@redhat.com https://www.redhat.com/mailman/listinfo/rest-practices
Mark Little mlittle@redhat.com
JBoss, by Red Hat Registered Address: Red Hat UK Ltd, Amberley Place, 107-111 Peascod Street, Windsor, Berkshire, SI4 1TE, United Kingdom. Registered in UK and Wales under Company Registration No. 3798903 Directors: Michael Cunningham (USA), Charlie Peters (USA), Matt Parsons (USA) and Brendan Lane (Ireland).
rest-practices mailing list rest-practices@redhat.com https://www.redhat.com/mailman/listinfo/rest-practices
aeolus-devel@lists.fedorahosted.org