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

[Tomaž Šolc]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi everyone

>> 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).

This generated a heated debate on our staff mailing list :)

I think the following sums it up why we went with this particular scheme:

> Some historical perspective: we modeled our API after Flickr's - that's
> where required parameters method, format and api_key come from...
> http://www.flickr.com/services/api/request.rest.html Flickr
> though/thinks it's REST, and we really didn't do a lot of thinking about
> this at the time.
>
> Being semantic-pedantic: REST paradigm is probably not suitable for APIs
> like ours, OpenCalais and similar at all. These APIs actually do more
> with the data, going beyond put/get/delete (state-transfer/update)
> paradigm which was invented (and post-hoc defined) mainly for handling
> the data inside web-alike data systems. Also POST/GET difference in
> definition of REST does not take into account technical differences
> between the two and unsuitability of GET to communicate big chunks of
> data, etc... Leading to the point that if you are semantic-pedantic
> about REST, when you apply it to an API like ours it breaks down on many
> different levels.
>
> So at the end, I think being RESTful is a "best effort" job.

Regards
Tomaž

- --
Tomaž Šolc, Research & Development
Zemanta Ltd, London, Ljubljana
www.zemanta.com
mail: tomaz at zemanta.com
blog: http://www.tablix.org/~avian/blog
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAksDytMACgkQyJ/LzBrnoEircwCg00hW+RrX/aKgiym6x+8osMF3
owMAnjp3Shkp/tvjhpE8358FKRJI01Fc
=jweg
-----END PGP SIGNATURE-----