Mailing-List: contact deltacloud-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: deltacloud-dev@incubator.apache.org
Received-SPF: pass (nike.apache.org: domain of tvvcox@redhat.com designates
 209.132.183.28 as permitted sender)
Message-ID: <4E3C1C62.6070408@redhat.com>
Date: Fri, 05 Aug 2011 18:37:54 +0200
From: Tomas Von Veschler <tvvcox@redhat.com>
Organization: Red Hat
User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US;
 rv:1.9.2.18) Gecko/20110617 Red Hat/3.1.11-2.el6_1 Thunderbird/3.1.11
MIME-Version: 1.0
To: Geert Jansen <gjansen@redhat.com>
CC: rhevm-api <rhevm-api@lists.fedorahosted.org>,
        aeolus-devel@fedorahosted.org, rest-practices@redhat.com,
        deltacloud-dev@incubator.apache.org
Subject: Re: [rhevm-api] Piece on RESTful API Design
References: <4E39D583.7010909@redhat.com>
In-Reply-To: <4E39D583.7010909@redhat.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

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.