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

[Bertrand Delacretaz]

Hi Tomaž,

On Wed, Nov 18, 2009 at 11:22 AM, Tomaž Šolc <tomaz.solc at zemanta.com> wrote:
> ...I think the following sums it up why we went with this particular scheme:...

It does, thanks for clarifying...we all live in the real world where
pragmatic compromises are often needed ;-)

-Bertrand

>
>> 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ž