Mailing-List: contact esme-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: esme-dev@incubator.apache.org
Received-SPF: neutral (nike.apache.org: local policy)
Content-class: urn:content-classes:message
MIME-Version: 1.0
Content-Type: multipart/mixed;
	boundary="----_=_NextPart_001_01C96D63.8E3070D3"
Subject: RE: Pretty scathing critique of our REST API
Date: Sat, 3 Jan 2009 06:23:38 +0100
Message-ID: 
 <30DB6ACF50A0A3439F39EFEB1C52E166078F2230@nets13ja.ww300.siemens.net>
Thread-Topic: Pretty scathing critique of our REST API
Thread-Index: AclkTWfWkOGCSwZ7RV+Vur6+SPMvRAJFgdC+
References: 
 <cdbebedf0812190504r26c1664fsfde76ba49f180c74@mail.gmail.com><30DB6ACF50A0A3439F39EFEB1C52E166078F2213@nets13ja.ww300.siemens.net><f767f0600812200130y56825546h3fdd2b4e24171e50@mail.gmail.com><30DB6ACF50A0A3439F39EFEB1C52E166078F2217@nets13ja.ww300.siemens.net><cdbebedf0812212111k7d618729r5d3a10a5844b0a74@mail.gmail.com><f767f0600812212345k2e967863j66a15b31c454932a@mail.gmail.com><cdbebedf0812220608q14750902n17622dcdcec2abd0@mail.gmail.com>
 <f767f0600812220752s692f12dey10067d4bdf8b47a5@mail.gmail.com>
From: "Hirsch, Richard" <richard.hirsch@siemens.com>
To: <esme-dev@incubator.apache.org>

------_=_NextPart_001_01C96D63.8E3070D3
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

Just added a disclaimer to our present REST API documentation at Google =
Code
=20
D.=20

________________________________

From: bdelacretaz@gmail.com on behalf of Bertrand Delacretaz
Sent: Mon 12/22/2008 16:52
To: esme-dev@incubator.apache.org
Subject: Re: Pretty scathing critique of our REST API


Hi David,

On Mon, Dec 22, 2008 at 3:08 PM, David Pollak
<feeder.of.the.bears@gmail.com> wrote:
> On Sun, Dec 21, 2008 at 11:45 PM, Bertrand Delacretaz <
> bdelacretaz@apache.org> wrote:
>
>> ...it 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 (
> http://apiwiki.twitter.com/REST+API+Documentation), 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
http://code.google.com/p/esmeproject/wiki/REST_API_Documantation

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

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

-Bertrand


------_=_NextPart_001_01C96D63.8E3070D3--