incubator-esme-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David Pollak" <feeder.of.the.be...@gmail.com>
Subject Re: Pretty scathing critique of our REST API
Date Mon, 22 Dec 2008 14:08:15 GMT
On Sun, Dec 21, 2008 at 11:45 PM, Bertrand Delacretaz <
bdelacretaz@apache.org> wrote:

> Hi,
>
> On Mon, Dec 22, 2008 at 6:11 AM, David Pollak
> <feeder.of.the.bears@gmail.com> wrote:
> > ...While technically correct, that the ESME APIs are not pure REST,
> barring
> > some study of the problems we're trying to solve and some suggestions
> about
> > how to solve them in a more RESTful manner, I think it's just a bunch of
> > folks who like to grumble about how uncool others are....
>
> FWIW, I had a quick look at
> http://code.google.com/p/esmeproject/wiki/REST_API_Documantation and I
> agree with the comments by jmettraux and dehora there - it would be
> more correct to call that API an HTTP/XML API.
>
> Doesn't mean the API is not cool, of course - but things like "GET
> /api/logout == destroy current session" make it easy for REST
> advocates to complain ;-)


Bertrand,

It's a delicate balance for us.

First, most of the folks I consult for consider REST APIs to be "simple HTTP
calls where the URL contains some of the parameters of the call (usually
some form of primary key) and the result can be hand-parsed."  Anything in
the minds of managers that's not REST is as difficult to use as SOAP and
they bristle.

Second, if one looks at Twitters nominal REST APIs (
http://apiwiki.twitter.com/REST+API+Documentation), one will find some of
the issues that we have.  Further, Twitters APIs are stateful (they're just
not documented as such) in that authentication is only required on the first
call and, if you pass cookies back and forth, the authentication credentials
are not needed on subsequent calls... and the /sessions/destroy POST will
end the session.  Further, Twitter (and most Rails apps) use the request
suffix as the key to the data return type.  According to the REST purists on
the Lift list, the app should ignore the suffix (in fact having a suffix is
very un-REST-like) and should rely on the HTTP headers to determine return
type.

I am keen to keep the REST designation for ESME's APIs.  I also think that
during the API clean-up, we can make them more REST-like including using
HTTP result codes rather than returning 200 all the time (this is something
that's been on the to-do list for a while), having stateless versions of
most of the calls (the calls would be identical, but if auth headers were
included, we'd skip the session creation bit), and using the headers and the
suffix to determine return encoding (XML, JSON, etc.)

I am keen to keep the REST (or REST-like or REST-inspired) designation
because is does convey simplicity, ease of use and quick uptake to folks who
are evaluating our project.  That's an important value.

Thanks,

David



>
>
> -Bertrand
>



-- 
Lift, the simply functional web framework http://liftweb.net
Collaborative Task Management http://much4.us
Follow me: http://twitter.com/dpp
Git some: http://github.com/dpp

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message