Damien Katz

The point of REST is HTTP caches. Caches aren't allowed to do anything with POSTs; but they can cache GETs and expire those cache entries based on PUTs and DELETEs.

And HTTP caches are a Good Thing. Not just because clients can use them to reduce the number of requests they send to you; but also because you can put a cache in front of your application code to reduce the frequency with which you regenerate pages.

Interesting Colin, I do use REST but I hadn't this caching perspective in mind.

Hi Damien,

I would agree with you that you understand a good deal of REST, but I suggest next examining the hypermedia constraint.

What SOAP (via WSDL) and most Interface based services do is prevent the independent evolution of the client and server. Many IDL based system break when even trying to add a new optional parameter somewhere.

The way I'm exploring the issue now is asking how many ways can I change the server _without_ breaking any clients. The URI and HTML Forms are the key expressions of how this works in a REST/Web hypermedia system.

Here are some of my current litmus questions:
1) Can I add a new optional parameter?
- HTML Forms supports this with default and hidden values.
- WSDL/IDL/RMI generally don't support this.

2) Can I relocate a service object (resource) to a new location?
- For example, I can move from a single server to three each managing accounts, orders, and customers by just returning re-directing URIs.
- An IDL based system would need to redeploy something into the client.

I see this as the critical difference:
A hypermedia system supports rich-linking and late-bound operation semantics supports evolution more effectively than an Interface based system.

Every Interface based system I believe suffers the same essential limitation: clients and servers have to evolve together. A hypermedia system doesn't have that same limitation.

Having said that, building a hypermedia based system is hard and different than most developers are used to. Plus, there is little tooling support today. I believe tools will get better, but the tools will essentially be limited by the dynamic and opportunistic quality of finding things instead of being hard-coded to expect them.

Thanks,
John

As Colin points out is about the various components within a systems architecture understanding the semantics of the operation. So caches, regardless of where they sit in the chain of a request, are one component that needs to understand the semantics of the operation upon a particular resource.

A simple example: doing a GET on a resource identified by a particular URL with an ETAG in the request entity meta-data can tell the URL resolver (in this case the browser) that the representation held in the cache is the same one that was requested last time, and since GET doesn't change things it is ok to return that representation without doing any more work...no network call etc.

At the end of the day ReST is a set of design principals that tell us how to design components/systems that scale in size and across different organizations boundaries. The Web's Architecture and HTTP's design were informed by these design principals and constraints.

BTW: if you look you will see a lot of similarities to Erlang's Process model and OTP design...

Well, a REST architecture serves as the basis for the most biggest and most successful information system the world has ever seen, that effortlessly deals with heterogeneous hardware and software, and provides a high-quality user experience while scaling towards a billion users. So think of it, as nothing else, as a good benchmark that you have to be better than.

Some things may require more than highly scaleable CRUD into a distributed flat namespace with rich multimedia handling; but maybe not that many.

REST principles are building blocks for the web and it has proven to be quite scalable and efficient. The major benefits include:
- separating reads from writes. I have worked on large ecommerce and travel website and one of the lesson is to keep your read/query services separate from your transactional services. REST APIs define separate operations for reads and write/updates.
- caching: you can find tons of off the shelf solutions for caching GET requests including hardware solutions. There are tons of features like ETags and cache headers that provide this feature.
- compression: Since REST uses HTTP, you can use compression such as gzip. This can improve the performance of the services.
- idempotency: GET, PUT, DELETE and HEAD are idempotent, which means if designed correctly the request can be retried without any worries about side effects. POST on the other hand is not idempotent and may have side effects.
- security: Though, security has been weakest area of REST as compared to SOAP, but HTTPS and simple authentication surfice. Though, there are better standards like oauth.
- big response size: REST/HTTP is the only service platform that I have seen supports gigabytes of responses. I have done a lot of CORBA based services in 90s, EJBs/SOAP in early 2000s and messaging based services for over ten years. None of those platforms support large size responses.
- simplicity: I find this is the biggest reason for using REST. I can use browser to call GET based requests and write client in any language.
- resources: REST response can include URIs for other APIs and client can change state through these resources. You can use XHTML to embed all these resources that can be easily tested with browsers.
- No need for additional jars - When I used CORBA, EJBs, RMI or JINI, I always had to put client/skeleton jar files. Having worked in large companies where I had to import dozens of these jar files became maintenance problem. With REST, I can simply call the service without importing anything.
The only real drawbacks I see for REST based services are that they are generally synchronous and blocking which can waste threads (though some of it can be solved with async I/O or event based dispatching). Personally I like to use messaging underneath REST services that provide asynchronous, persistence, and better reliability.

One of the big (but non-immediate) wins is explorability. If you don't care about emergent properties, if you don't care about what other people might build on it, then sure, use nothing but POST; use SOAP; use CORBA, for that matter. The magic of REST is that no WSDL or IDL can replicate the experience of someone clicking around a RESTful API in their browser like a kid opening up a box of Tinker Toys and saying "yeah, I get how this fits together! I could build on this!".

I think only allowing up to 4 methods is a key benefit. Having to express an app through nouns rather than verbs leads to a much cleaner, more robust and encapsulated design.

Hey y'all, youse using you a big bunch of words that the average fella don't understand. REST, SOAP, PUT, GET, POST, COUCH? WHAT?

The only time I use these words is when I come home from work, I do stuff like

Tell ma wife to GET me a beer, fall on the COUCH, PUT my legs on the table, check if I got any new POST, switch to channel RPC to see what game is on. And when it's time to sleep, go put on some SOAP, before I go to the bed and REST.

Perhaps PUT and DELETE make sense to help the caches out (though they do make debugging more difficult; typically I'll make a _method query string parameter synonymous) but some people advocate such things as using the "Accept" header to determine return types, which seems unnecessary. Why scatter your "inputs" across four different locations: the URL, method, post parameters *and* headers?

The exotic HTTP-methods (PUT and DELETE, most notably), often gets associated with REST, which I find a bit unfortunate, since this is mostly an implementation detail. The really important premise of REST, is to use HTTP as a first class protocol, rather than something to be abstracted away.

I think REST is the last stop for HTTP in web services. XMPP's PubSub and AMQP will stop senseless polling for changes.

I wrote a (not so) little something on where I think there's some right and wrong in this post and the comments:

REST, I just want it: http://cdent.tumblr.com/post/46065676/rest-i-just-want-it

"If its easy to make all your calls conform to the RESTful verb architecture, then that's good, I guess. But if not, then just use a POST as an RPC call, keep it as simple as possible and be done with it."

Well this is a pretty scary statement coming from the developer of CouchDB...

If you're going to expose your interface using HTTP you should at least take the time to understand what the underlying architectural style is and be guided by the constraints inherent therein.

To highlight Shahzad Bhatti's point which directly answers your question:

PUT is guaranteed idempotent, but POST isn't.

This means you can repeat the same put request repeatedly knowing you won't change the state of the resource (or create more resources).

POST however does work as a great as a factory method.

The REST architecture does have lots of benefits which have been thought about. It's not just religious dogma.

If you enable access to your information items via POST only, you can't link to them. No bookmarks, no casual emails containing a link, no debugging via the browser, no possibly to use links in the data you exchange.

This is by no means the only downside of tunneling through POST, but it's certainly the most obvious one.

Amen, brother.

Keep burning those sacred cows!

The only thing I take away from these comments is that there is no consensus understanding of what REST even is. Some of the comments were so confusing and at odds with what I knew as REST that I wonder if we are even talking about the same thing.

To me REST is nothing but the following: lightweight, stateless* object (resource)-centric messaging over HTTP.

* stateless as in the connection is either dropped or reset between requests, not necessarily that the server or client states are reset

Let's call that the "REST foundation".

That's all it is fundamentally, but riding along on the same wave is the "REST convention" - a general community consensus that simple is best and to try to use the HTTP default actions whereever possible. This is all great.

However, it's no panacea. I can think of *countless* examples where the REST convention totally breaks down and you're basically doing RPC in POST (or massive, ugly GETs - until you run out of space that is!) and you're SOL REST convention-wise.

The REST conventions are great as far as they go but unless you're building nothing more than a CMS I can't see how anyone could possibly argue that it's all anyone needs. I also don't see any point in bending over backwards trying to shoehorn your app into a REST convention design. People talk about "discoverability" but I can't see how that would work except in the most trivial examples.

To me, the real breakthrough here is the REST foundation, the possibility of standardising on HTTP everywhere, the statelessness, and the use of the simple-case REST conventions where appropriate. Trying to insist on "purity" is ludicrous and I wonder if anyone arguing in that direction has ever tried to build, or even design, an app which would truly adhere to the principle they're espousing.

REST is by no means a comprehensive solution to everything. Go look at the still-ongoing debate about how to GET multiple resources at once in the CouchDB ML for an example of just how loose and ambiguous it really is.

POST as RPC call is everywhere, completely non-controversial, and the web has survived this far. I am with Damien on this. Use REST until you can't any more, then come up with your own solution while staying with the general principles. Works for me and I'm encouraged to see the pragmatic approach winning in CouchDB.

"there is nothing wrong with a plain old POST as an RPC call."

Damien,

That's true when you actually need RPC and need to tunnel it over HTTP, but assumes that RPC is a good way to think about building Web systems.

RPC from browser to server is a lousy programming model for the Web. One of the many things making REST an interesting model is that the fundamental model is not the remote procedure call. Instead there are notions like resource transfer, links between resources, and a uniform interface.

The big deal isn't PUT and DELETE.

The Web -- the parts of it that work well in the real world -- work in part because the common interactions aren't much like procedure calls. They're much more about shipping resource representations from one place to another, and using those representations to find new resources. Since those new resources obey a well-known uniform interface, you can interact usefully with them as soon as a reference to them is discovered.

Well, I think it all boils down on REST vs. RPC. Do you feel alright with Services and service calls? Fine, go with RPC, not necessarily SOAP.
If you want to go resource-centric, go REST. It is an architectural style, and not the center of an architecture.

I hope you all get your wish someday and rise to the position of Chief Architect of Blowhard Web Services in your respective companies.

Personally, I prefer a blend...

Your application should support a standard SOAP interface with HTTP POST for any service that modifies data. For read-only requests, a HTTP GET based URL that returns a SOAP response gets you everything useful that REST fanboys demand.

Most of what REST purists demand strike me as odd, arbitrary, or asinine.

Limit yourself to only four verbs? The holy war that demands that 'action' parameters in the URL be BEFORE the '?' instead of AFTER? Forcing people to use PUT, HEAD, and DELETE to better mirror the crap in CRUD? Assuming that the only valid cache is a HTTP cache?

Seriously... how bizarre...

Thanks for the post... I'm glad to see some sanity in this debate.

THANK YOU for saying this. Glad to know I'm not the only one. I'm also in the camp of "yes SOAP sucks, but what problems does REST solve?"

The more a service looks like a filesystem, the more REST makes sense. The more any of its operations diverge from being dumb filesystem operations, the more REST breaks down, and the worse of a fit it is.

If you haven't read it already, I recommend RESTful Web Services for a good, practical explanation of the benefits. I'm sure you could get one of the authors to send you the best of the chapters...

I think the point is being missed that REST is not supposed to give you some kind of additional functionality. Quite the opposite, it is supposed to to limit and guide your app design. It is just an API pattern which seems to work very well for a lot of web apps.

"a REST architecture serves as the basis for the most biggest and most successful information system the world has ever seen"

I agree, except that PUT and DELETE played no roll in this whatsoever.

It's a bit shocking that anybody who claims to understand the web would suggest that GET isn't necessary and everything can be done with POST. PUT and DELETE are "debatable" but GET is the cornerstone of the web and the entire idea of an information network. Your post suggests such a simplistic capacity that you really ought to do some actual research and make a serious attempt to understand the matter at hand instead of making such silly blog posts.

Can somone explain how the cache (and its invalidation using PUT and DELETE) will work in a web-farm situation?

thanks

As a follow-up to John Heintz's comment above:

>the tools will essentially be limited
>by the dynamic and opportunistic quality
>of finding things instead of being
>hard-coded to expect them.

Which is essentially the difference between static and dynamic typing, isn't it? I find that most of the discussion of REST vs. SOAP matches the discussion of dynamic languages vs. static languages.

I did the homeworks, read the book about restful web services and built some deadly-simple ("big") web services (mostly for university assignments, though).

So these are my thoughts. SOAP (and RPC in general) services are designed to be consumed by machines, while restful services are supposed to be consumed by both machines AND human beings. This is, IMHO, the big difference between these styles/technologies.
And about the 'fake' or 'circa' (make your name) restful services, which uses some overloaded posts to accomplish rest-breaking tasks, well, I will start to think about the back-end resource design, in first instance. Maybe with a different design, those overloaded post can be avoided --whatever this is useful or not, depends on you as developer IMHO--.
But yes, I think that RPC-style services *still* can be, if not necessary, the best approach:
as an example, I'm working on a mobile applications which uses *heavily* the overloaded-post style to sending and retrieve data from the server: this was needed because of some factors, namely 1) here in italy we faced the fact that some network simply don't know protocols != HTTP (so, no custom TCP/IP protocol), 2) here in italy we don't have a really cheap network on mobile, so we ended up putting *a lot* of info in a single response and decided to avoid SOAP, because of the xml-encapsulation overhead.

Last but not least, if you are offering information that you actually WANTS to be available to people, then you cannot forget about search engines. Follow the rest rules, use html as your native format representation (or at least link to pages which are actually plain html, istead of building *everything* the ajax-way), and your data will be available for the search.

That said, hey Damien, couchdb is a great piece of software, keep up the good work :D !