Has REST Been Fortunate in its Enemies? ·
I have been among the most vocal of those sneering at WS-*, and I’m
comfortable with what I’ve said. But that doesn’t prove that the core WS-* ideas
are wrong. Here are some of the handicaps WS-* struggled under:

Lousy foundational technologies (XSD and WSDL).

A Microsoft/IBM-driven process that was cripplingly product-linked and political.

Designers undereducated in the realities of the Web as it is.

Unnecessary detours into Architecture Astronautics.

As a result, we should be really careful about drawing lessons from the
failure of WS-*. Specifically:

Just because the XSD type system is malformed, you can’t conclude that
the notion of schema-driven mapping between program data types and
representation payloads is harmful.

Just because WSDL is a crock, you can’t conclude that exposing a
machine-readable contract for a service is a necessarily bad idea.

Just because UDDI never took off, you can’t conclude that service
registries are dumb.

Just because SOAP has a damaging MustUnderstand facility and grew a lot
of ancillary specification hair, you can’t conclude that some sort of
re-usable payload wrapper is necessarily a dead-end path.

Just because the WS-* security specifications are overengineered and
based on a shaky canonicalization spec, you can’t conclude that
message-level security and signing aren’t sometimes real important.

And so on. I personally tend to think that schema-driven mapping is
hopeless, contracts are interesting, registries are a fantasy, and
payload
wrappers are very promising. But I don’t think that the history of WS-*
is a very good argument for any of those positions.

Is Getting HTTP Right Good Enough? ·
REST, say its aficionados, is more than just HTTP. And that’s true in
theory. But in practice, there are a whole lot of benefits to just getting
HTTP right. Suppose just hypothetically that your app violated a bunch of REST
precepts, say by making heavy use of cookies and never embedding hyperlinks in
what it sent. But suppose also that it was a really good HTTP citizen;
getting the caching
right, not misusing POST, and taking advantage of idempotency where
possible.
Well, you know, it might be a pretty good app, and scale startlingly well.

The reason that this scenario feels a little strained is that who’ve
come to understand HTTP have usually picked up some of the rest of the REST
canon along the way, and put it to use.

That granted, I think the benefits from getting HTTP right are really
really big; enough that they’re
worth pursuing even if you don’t care to join any four-letter religions.
And if you’re trying to explain to management why you’re working on sweating the
HTTP details, just tell ’em you’re doing REST and you’ve got buzzword cover.

What Does “Hypermedia as the Engine of Application State” Mean, Really? ·
I’ll be honest: I’m not sure. On the
other hand, one of the great advantages of being resource-centric, as in
giving everything you care about a URI, is that whatever kind of messages
you’re shipping around the network, URIs are easy to pack into them.
And experience to date suggests that doing this leads to good results.

Is Statelessness Required? ·
It’s really easy to understand why, in an ideal-world network application,
if none of the client implementations contain state, the scalability
payoff can be huge. In the perfect REST world, state lives in
resources, resource identifiers, and the representations you pump around the
net.

Well, yeah, but in this world, that’s hard. For example, one of the places state shouldn’t
live is in cookies jammed down clients’ throats. It says so
right
here in Roy’s thesis.

But damn, they’re useful. My intuition is that the architectural flaws are
small enough, and the convenience-function benefits large enough, that they’re
with us for the long haul.

And I think there’s a lesson here: that statelessness, like many other
good things (Buddha-nature,
purely descriptive
markup) is an Aristotelian virtue; unattainable in an absolute sense, but
rewarded to the extent you can practice it.

Is Being Message-Centric Good Enough? ·
The Web is attractive and thought-provoking because it succeeded in scaling
to meet the needs of a global heterogeneous network where many had failed
before, most notably CORBA and DCOM. The most obvious differentiator is that
those other network programming frameworks tried to extend the notions of
API and Object Model across the network. The Web doesn’t do APIs or Object
Models; it’s just a set of protocols, agreements regarding the exchange of
short series of messages, and what has to be in those messages.

My single most deeply-held conviction about network computing is that
attempts to abstract away the underlying message traffic are
in the long run doomed. So hmmm, maybe is it not only good enough to do HTTP
right, maybe all you need is to face up to the fact that it’s all about message
interchange, and proceed from there (of course, you’ll probably end up
inventing something essentially like HTTP).

Are PUT and DELETE Essential? ·
During the design of AtomPub, a few people, including me, worried out loud
about the use of PUT and DELETE in the protocol,
simply because those functions aren’t supported in browsers, hence also not in
servers, and are not available at all to programmers on the dumber class of
mobile devices.

We were shouted down by the purists, who said that PUT and DELETE are
essential features of the architecture. And they had good arguments,
especially around idempotency and ETags for safe concurrent update.
But you know, unlike most other REST conversations, those are arguments from
theory not practice. I’m pretty convinced that AtomPub would work about as
well if you overloaded the U and D in CRUD on POST, carefully and
respectfully.

Having said that, I’m beginning to believe that the theoretical benefits of
PUT will work out pretty well in practice, and I’m glad that AtomPub now gives
PUT something useful to do.

Is “Do Like the Web” a Good Argument? ·
A common argument from REST proponents is “The Web works pretty well, so
shouldn’t you be taking
Web Architecture seriously as you
go about your engineering?” For a recent example, see
my
comment on Damien Katz’s piece linked above.

While Damien is
unconvinced,
I think it’s actually a pretty good argument. I’ve never talked to Roy about
this, but my perception is that REST was reverse-engineered from his
understanding of what makes the Web work, based on having been there when some
of the most important pieces were being built. And judging by my experience
of getting Web stuff to work, Roy’s understanding is pretty much on the
mark.

Anyhow, all the other strong REST arguments are theoretical. There’s a lot to
like, on engineering-aesthetics grounds, about decentralized flat identifier
namespaces, about the notion of Resource and Representation, about
statelessness, about hypermedia, and so on. But all my favorite engineers are
most impressed by arguments from practice not theory: “See, like
that.”

Where Are the Tools? ·
I’m on record as thinking there’s not much out there. Let me be specific
on what I mean by tooling: facilities for use by programmers that do away with
redundancies and irritants and boilerplate; that let you do things faster and
better.

Once you get past
ActiveResource,
Restlet, and
Jersey, I’m not aware of much (but
I bet there’ll be some shout-outs in the comments).
Seems like an opportunity to me because, you know, REST really actually truly
works, as religions go it’s a very practical one.

Updated: 2008/08/18

Contributions

Aggregate a whole pile of use cases, and the WS-* stack shine compared to rest.

Disclaimer: I haven't been involved with either since about 2003. But even back then, there was a lot of good stuff that could be done with SOAP and WS-* stuff, despite the use of XML Schema within WSDL.

Err… ’scuse me? Clients are *supposed* to keep state – REST calls this application state. What REST says is that *application* state should not live on the server. F.ex., in FTP, the server is responsible for keeping track of the client’s session state (what’s the current directory, what’s the transfer mode, etc.). In RESTful protocols that is the client’s responsibility alone: the client keeps all the application state. (Conversely, the server keeps all the resource state. It also makes all of it addressable via URIs.)

The client then affects resource state by sending representations of resources, and in turn the server affects application state by sending representations of resources. That’s where the “Representational State Transfer” term comes from.

The Google Data APIs (which I work on for Google) support the HTTP header X-HTTP-Method-Override, which allows you to wrap a PUT or DELETE inside a POST. Set the header value to PUT or DELETE, do a POST, and Google will treat the request exactly like an actual PUT or DELETE.

I'm working on a REST API for Gliffy (online diagramming tool). There were many issues, but to be honest, REST as a design approach worked great. Our API is basically CRUD, and it just keeps things incredibly simple.

Since, as you mention, there is not much in the way of software for implementing REST, we rolled our own, which we will be open sourcing once it's somewhat releasable. Jersey and the Sun spec for REST look needlessly complex to me, and don't handle a lot of things very cleanly. I don't think annotations were the right design, e.g.

Anyway, one thing that REST is very poor at is in communicating errors back to the client. You have two options: bind it to one of the HTTP errors and hope that the client can provide a decent UE from that, or tunnel your errors over 200/OK in a custom format. Both are pretty annoying.

Hi, Tim, thanks for a great post that adds several important arguments about REST to the table.

Apart from Rails implementation of REST, you've mentioned two Java implementations, rather than "tools" - Restlet and Jersey. While Jersey is a library which is a reference implementation of JAX-RS (Java API for RESTful Web Services), Restlet is a framework for building RESTful applications which has a JAX-RS.

The nice thing about JAX-RS, which is developed under JSR-311 community process which is progressing nicely, i.e. (much) more efficiently that JSRs are infamous for, is that it brings to life the nice declarative programming style using annotations. You might want to check it out.

Imagine having this:

@Path("/spec")

public class SpecificationResource

@Path("/jsr/{id}")

@ConsumeMime({"text/html", "application/xml", "application/pdf"})

@GET public Document getDocument(@PathParam("id") String id) {

// You get the point... ;-)

}

Other Java implementations of JAX-RS specification out there are Apache CXF and JBoss RESTeasy.

Regarding tools for the actual testing of RESTful applications and web services, I happen to know that recently awarded soapUI is starting to include support for REST.

I like all your points and was convinced to pursue a REST-style architecture for a new application I'm designing. When it came time to put the design into practice, though, I was put off by the lack of tools, specifically for Java. Jersey is not yet a 1.0 technology and Restlet isn't as well-documented as I'd like. We've put the project on hold, so I'm hoping that Spring Framework 3.0's implementation of REST will provide some kind of answer if it comes out in time. Otherwise, I'll have to go with POX as an intermediate solution.

We use X-HTTP-Method-Override in NewBay; practically a necessity for mobiles.

One of reasons I like having PUT is that it can be dedicated to doing the overwrite thing (as per Gdata). That keeps POST free for other work. In the future I think we'll use POST for delta updates direct to entries and wonder wtf were we thinking with all the delta stuff. Not having DELETE is just weird, but I'm highly sympathetic to client mobile and browser developers who are limited to GET/POST.

@Tim Bray:

"I’m not sure." Try working to web2.0 APIs that don't send back links (either nothing or IDs). The clients get coupled real fast. Or imagine trying to drive an AtomPub client without the Content* headers.

"Is Statelessness Required?" - I agree with what you've said for soundbite purposes, but there's a lot more to "state" that you let on here; eg, Cookies can be fine if you know what you're doing.

"We were shouted down by the purists" - Links please :) We're a few years on now, but my guess is someday you'll be glad that updates were kept off POST.

The tooling problem remains quite serious imo, especially in the Java and PHP worlds. "Where are all the REST toolkits" still rings in my ears. Ruby and Python people seem to get by fine these days.

Tim says: "We were shouted down by the purists, who said that PUT and DELETE are essential features of the architecture. And they had good arguments, especially around idempotency and ETags for safe concurrent update."

We were also fairly successfully tackled the "PUT/DELETE not supported in browsers and thus servers" by producing working code for a number of scenarios, Ajax, Perl, PHP.

Just to remind ourselves, the choice of REST wasn't just a theoretical talking point, and that was one of the great things about the Atom group - the willingness to accept working code as rationale.

I'm still vividly remember the days I spent toiling through Orange vs Carrot learning about REST, and then writing code to prove that REST can and does work in a typical development environment.

While an envelope/wrapper makes sense, using XML as an envelope/wrapper does not, for a variety of reasons.

If you fixed the problems that arise using XML as an envelope/wrapper of independent parts, the result would look a lot like MIME, which, surprise, unlike XML was designed as an envelope instead of as a structural hierarchy and is already being used by a number of successful approaches to web messaging.

Good stuff. Lack of tooling is indeed somewhat problematic, but equally so are the habits that bad/inadequate tools got us into (server-side session state, unsafe get, forgetting about HTTP's caching capabilities, etc). REST is something of a new mindset, and while "simple" at some level, by no means easy. And there are some tools I couldn't get by without at this point: Firefox (and varous extensions such as Poster), Firebug, and curl chief among them.

I'm quite the REST noob and still naive on many of its fundamentals, but the issue that has most irked me about its proponents is their disregard for the importance for the statelessness they claim underlies REST architecture. As you pointed out, in actual practice most REST-based systems actually store some state data on clients in the form of cookies. After reading your article I now consider that such stateful cookies might be a practical caching solution to bypass authentication latencies, but the problem remains that key pieces are still lacking to get a fully-stateless RESTful HTTP right.

To move forward, someone needs to come up with an architecture that is compliant with REST principles without depending on stateful cookies or other similar crutch, which may let us get problems solved today, but don't force us to develop a complete working RESTful implementation. Otherwise, as you stated, REST may be ideal but not completely practical.

I mentioned on Damien's blog that I kind of share his thoughts when he posted them originally. "The web is built on REST. Therefore REST is good" Bullshit". Mainly because there is still a little confusion on what exactly REST is? As a technology person, I sure wish REST had some very, very distinct features. Even with AJAX: some people describe AJAX oriented applications in generic terms, but you get an image of what an AJAX oriented application looks like in spite of the fact that the AJAX application could use XML or plain text, or a variety of different distinct APIs (like with jQuery or Prototype).

What is not distinct about REST. Let me ask this question, is there a REST RFC? Could one be implemented? What if a server or client library fails to implement the features properly, is it still REST?

So here are my questions and my theoretical answers?

Q1: Lets say I don't get HTTP right. I don't use PUT, I don't use DELETE. I use a heavy RPC oriented XML messaging format in POST requests. Heavy requests. Am I building a REST application?

For example. A lot of yahoo's api claim to be REST or REST like. But a lot of them seem like you are sending XML RPC data to yahoo endpoints as detailed in this documentation.

"A RESTful web application requires a different design approach from an RPC application. An RPC application is exposed as one or more network objects, each with an often unique set of functions which can be invoked."

Q3: When people describe a REST application. What in the world are they talking about. Could people please be more specific when they describe REST. E.g. REST using the following APIS like Restlet. Also, what is REST-like, RESTful. For example, Dave said the following:

"Anyway, one thing that REST is very poor at is in communicating errors back to the client. You have two options: bind it to one of the HTTP errors and hope that the client can provide a decent UE from that, or tunnel your errors over 200/OK in a custom format. Both are pretty annoying."

If REST is essentially getting HTTP right? Why in the world would it be hard to communicate errors back to the client?

Q4: HTTP has some clear properties. If you are building a web application that doesn't use GET or POST...that isn't really a robust web application. What are distinct properties that define a REST architecture. If there aren't any, is REST just a theoretical description of getting HTTP right?

Regarding state, there are two kinds that are important to think about: resource state, and application state. Resource state move back and forth between server and client (via GETs, POSTs, etc). Application state, per REST, needs to stay on and be controlled by the client. The problem with cookies is typically that they refer to application state on the server. As Stefan Tilkov says, that's a wasted opportunity. Don't hide it -- if a user has some items in a shopping cart, give that cart an address and allow operations to be performed on it. Serendipitous reuse and cleaner separation of concerns may very well result.

Ajax-type application are particularly suited to maximize these opportunities. I typically set a cookie in the browser identifying the current user (the value of which is delivered to the browser in hypertext upon login). The cookie is never sent back to the server as such, but does allow me to create (ajaxily, with javascript and XHR) user-specific URLs (username included in URL) to get things like cart content, etc. These are used to asynchronously "decorate" a generic same-data-no-matter-who-is-asking-for it page. I've seen real benefit to such an approach.

@Shonzilla: Jersey is a framework, that implements the JAX-RS API, for building RESTful Web applications i.e. it is the RI and more. It is designed to be highly pluggable and easy to integrate into other frameworks.

@Dave: If you feel inclined to provide more information i would be interested to understand more about your objections to the JAX-RS API. What did you find complex? You could provide feedback on the proposed final draft by sending email to: users@jsr311.dev.java.net.

Whenever I see the "Where are the tools?" argument I get a bit confused. People seem to want some kind of extensive framework to manage their REST API or their RESTfulness or what have you. On the web, the framework is HTTP itself, and most of what you need in terms of a framework is something to dispatch from URLs to code and a bit of glue to get things to hang together.

I'm sure I've been spoiled by Python and WSGI (where cooking your own framework behaving system is dead easy but I really bristle at big F frameworks that hide a bunch of what is fairly straightforward (and educational) stuff behind what, to me, is magic. Some of the boilerplate that people want to abstract away is the stuff that clearly demonstrates and nails home the coolness of a well designed REST API. If the framework does too much of the work that coolness doesn't get learned and it isn't integrated into future designs.

"Mainly because there is still a little confusion on what exactly REST is?"

It's an architectural style. I think the confusion is that people confuse "architectural style" with "architecture" and "protocol", neither of which an architectural style is.

"As a technology person, I sure wish REST had some very, very distinct features."

It does, only the thing to remember is that it is neither an architecture nor a protocol, but describes a set of useful and interrelated properties an architecture or protocol fitting it would have as well as the benefits and demerits resulting.

The confusion here is that people are committing a reification fallacy: they're taking something abstract and treating it as if it's more concrete than it is.

"Even with AJAX..."

That's apples and amoebas. AJAX is quite a concrete thing: making HTTP requests in Javascript within a browser.

"Let me ask this question, is there a REST RFC?"

No, but there could be, and it'd be informational.

"Could one be implemented?"

Based on REST, you could 'implement' it, after a fashion, by designing a protocol based on REST.

Let me put it this way: a protocol or architecture is a reification/'implementation' of one or many architectural styles. Similarly, an application or system is a reification/implementation of one or more protocols and/or architectures.

"What if a server or client library fails to implement the features properly, is it still REST?"

Clients and servers don't implement REST, they implement RESTful protocols. What they're doing is implementing or using the protocol incorrectly by going against its grain.

"Lets say I don't get HTTP right. I don't use PUT, I don't use DELETE. I use a heavy RPC oriented XML messaging format in POST requests. Heavy requests. Am I building a REST application?"

PUT and DELETE have nothing to do with REST. You're confusing REST's uniform interface constraint with how HTTP implements it. RPC as an architectural style (yep, it is!) is diametrically opposed in most regards to REST, so no, it wouldn't be RESTful. The Flickr API is RPC, plain and simple. The same goes for the 'RESTful' Twitter API and the 'RESTful' Last.fm API.

"Can you use custom XML RPC formats with REST?"

I'm not quite sure what you mean, but if you mean using XML-RPC as an object serialisation format similar to JSON, sure, but that's as far as it goes.

"If REST is essentially getting HTTP right?"

Yes and no. Using HTTP in a RESTful manner is getting HTTP right, but HTTP is not REST, it's protocol that adheres to the REST architectural style.

You know, I think the "REST tooling" discussion leads one's thinking down the wrong path. IMO, one of the strengths of REST is that you're not allowed to overlook the nature of the network. Most of the "tools" I've seen go out of their way to hide the network from you, to your detriment. PHP, for example, is terrible, because most of its HTTP client methods completely existence of status code and headers. It doesn't allow you to use any of the things you need to use -- verbs, cache headers, If-Match, range requests, content-type negotation, etc.

Nearly every discussion regarding REST toolkits or frameworks I've been a party to seems like it's been an excuse for bozos to paper over the network in their API. "Oh, we'll just raise an exception when we get an empty body back, no one will ever want to send one of those legitimately, right?" "Let's set the expiration one year in advance, because it's easier to go around to each cache and explicitly invalidate whenever something changes." "My client is better because you can change your requests from POST to GET via a configuration variable -- no code has to change!" This sort of thinking is what comes to mind when I hear about "REST tools".

What I really want is a toolkit that exposes HTTP to me completely in all its details. Give me an API to easily read headers and set them, especially for those fiddly media-type semicoloned monstrosities. Make it easy to request ranges, transparently gzip the body, save a cache of etags with associated urls on the client. Make it easy for the server to save computation via the if- headers. Validate my logic, warn me if I respond with a 302 without a location header (don't do the PHP thing and take the existence of a location header to mean that I wanted a 302).

I've been using a custom-built REST-ful library for IIS called exyus (http://exyus.com). Much like Jersey, it uses a code class that defines a resource. Unlike Jersey, the base class has public methods that match HTTP Methods. Regex is used to route URLs to the resource class. Representations are handled using XSL Transforms of the storage data. It handles conneg, caching, and authentication without much cruft.

Just a quick word about RESTful tooling for developers, and the lack of it.

First, there is already bucketloads of tools out there in the guise of HTTP support. When most people say REST, they mostly mean HTTP and there aren't many platforms that hasn't got HTTP support, big or small. You can do REST in pretty much anything these days, as opposed to WS-* which require something extra.

Second, to implement a basic RESTful system of sorts is actually really easy and do not require a RESTful tool or framework or library to get you going. You can leave a great deal of HTTP caching and such to your favourite web server with a bit of clever wrapping, mixing application-run and static resources. My first RESTful app was without any tooling, and took me marginally longer than what I'm currently doing with a REST framework.

In regards to those complaining of no tools for Java... well, I am using Jersey. Today, I downloaded the jersey trunk, the jsr311 trunk, built them using maven, which I've never used before. I then moved the few jar files into my WEB-INF/lib dir, added the couple of lines to web.xml, and put in a very simple resource class. Total time, < 1 hour. 50 minutes of which was getting the projects, and building them (tons of unit tests). I do not understand the need for tools if it's so easy?

And by the way, Netbeans DOES have a plugin for Jersey that allows you to use a GUI wizard to add resources. I frankly prefer the manual approach, as it actually took me less time.

Now, I gotta ask, and from the names I see.. some of you are pretty dang big names in the Java world, why is this so hard?

One post said Jersey isnt 1.0 so cant use it, put it on hold? Huh? AS of now its FCS and finishing up in a month. Why not get started since it's pretty close to being final.

For the one saying annotations is not the way a RST based api should have been built.. well, all I can say is I was afraid of annotations until I tried Jersey and EJB3. Now I am a believer. It's amazing how much time and effort they save. Frankly, Jersey does a really good job with the annotations and how they use them to map paths and such.