incubator-esme-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Hirsch, Richard" <>
Subject RE: Pretty scathing critique of our REST API
Date Sat, 03 Jan 2009 05:23:38 GMT
Just added a disclaimer to our present REST API documentation at Google Code


From: on behalf of Bertrand Delacretaz
Sent: Mon 12/22/2008 16:52
Subject: Re: Pretty scathing critique of our REST API

Hi David,

On Mon, Dec 22, 2008 at 3:08 PM, David Pollak
<> wrote:
> On Sun, Dec 21, 2008 at 11:45 PM, Bertrand Delacretaz <
>> wrote:
>> would be
>> more correct to call that API an HTTP/XML API....

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

Ouch. I understand how you might have to use terms like "REST-like" to
explain things to such managers, but I'm not sure if it's a valid
excuse for abusing the term in specs ;-)

> Second, if one looks at Twitters nominal REST APIs (
>, one will find some of
> the issues that we have..

Ok, but at least there they say "The Twitter API attempts to conform
to the design principles of Representational State Transfer (REST)" -
note the word *attempts*. Such a disclaimer might be good at

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

Yes, and that's IMHO one of the "rules" that today's browsers often
force us to break.

> ...I am keen to keep the REST designation for ESME's APIs....

Being just a mentor here, I'll leave that decision to people who are
actively involved in the project, but my opinion is still that the
current API would better be called either an HTTP/XML API, or a

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

Cool. One thing that I notice also is that the current API is not
suitable for caching, as resources deliver varying content depending
on a session state.

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

I see what you mean, but cannot agree to call the current API a REST
API. That might give a warm fuzzy feeling to "customers", but might
have the opposite effect on technically competent people.
"REST-inspired" sounds much better, especially given the intention to
improve things.


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