[iks-community] Some guidelines to document API of RESTful services

[Bertrand Delacretaz]

Hi Olivier,

Thanks for your input!

Just a few comments in line, in general I agree very much with what
you're saying.

On Mon, Nov 16, 2009 at 11:44 AM, Olivier Grisel <ogrisel at nuxeo.com> wrote:

> ...I think it is also a good practice to offer a sample HTML / Javascript
> application as a demo client for the service....

I'd go further and provide automated test cases (using dummy semantic
plugins if needed) that actually demonstrate how the API work, and
verify that it does.

That's not always possible (like: if we don't have an implementation
yet;-) but if you can do that that's the best way of "documenting" all
the actual details.

> The public Zemanta API is also a good example of such RESTful API documentation:
>
>  http://developer.zemanta.com/docs
>
> However, there is a problem with this API: the URL is always the same
> and the "verb" of the method is passed as a JSON keyword arguments.
> This is not really in the spirit of RESTful APIs and it would be nicer
> to make the method name explicit in the URL pattern as twitter does....

I agree (and you're being polite ;-), passing method names as
arguments is definitely not RESTful.

Instead of doing a GET on a generic URL and including a parameter that
says "please call the suggest method", for example, the RESTful way
would be to do a GET on a "suggestion engine" URL, like you suggest.

(with all due respect to Zemanta - their stuff is great, but like many
so-called RESTful APIs out there it's not a good example of
RESTfulness in this case).

-Bertrand