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

[Michael Marth]

+1: compromises are needed in the real world

Having said that, I would like to throw in another example for a REST API,
which I consider a really good one, the Kenai API [1]. They treat all
entities as resources (i.e. everything has a URL) and Hypertext is used to
navigate between resources (aka the HATEOAS constraint) (try [2]).

Again, there's no need to be pedantic about REST, as long as whatever we do
gets the  job done, but there's no harm in looking at good examples either
;)

Cheers
Michael

[1] http://kenai.com/projects/suncloudapis/pages/Home
[2] https://kenai.com/api/projects

On Wed, Nov 18, 2009 at 11:32 AM, Bertrand Delacretaz <
bertrand.delacretaz at day.com> wrote:

> 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ž
> _______________________________________________
> iks-community mailing list
> iks-community at iks-project.eu
> http://lists.iks-project.eu/cgi-bin/mailman/listinfo/iks-community
>



-- 
Michael Marth | http://dev.day.com/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.iks-project.eu/pipermail/iks-community/attachments/20091118/779b8742/attachment.htm>