REST is a scam.

For most people, REST is simply the negation of SOAP. They should really use some term like POX (Plain Old XML) or POJ (Plain Old JSON) for simple RPC protocols implemented over http.

If I still was interested in being a maintenance programmer, I could make a pretty good living fixing broken systems based on people who drank Fielding's Kool Aid.

For instance, I once saw a Silverlight app that took 20 minutes to initialize because it traversed a tree of relationships using REST. It started out O.K. but as the app grew more complicated it took tens of thousands of requests and an incredible amount of latency.

I reorganized it so that it got all this information in one POX call that took 2 seconds. A bad architecture slowed the application down by a factor of 600 and made the difference between something that would have worked and something that failed.

People who are building toy applications can blubber about "the decoupling of the client from the server" but the #1 delusion in distributed systems is that you can compose distributed operations the same way you compose function calls in a normal program.

The issue is that the latency involved in a distributed call is about 100 million times more than that involve in a function call, and the failure rate is more than 10 trillion times more. All of the great distributed algorithms such as Jacobsen's heuristic for TCP and Bittorrent have holistic properties possesed by the system as a whole that are responsible for their success.

Hypothetically you could deal with the reliability problems of REST applications by using distributed transactions, but so far as performance and latency goes, this is like putting out a fire with gasoline.

Security is another problem with REST. Security rules are usually about state transitions, not about states. To ensure that security (and integrity) constraints are met, REST applications need to contain error prone code that compares the before and after states to check if the transition is legal. This is in contrast to POX/RPC applications in which it is straightforward to analyse the security impacts of individual RPC calls.

REST is an anti-anti-pattern where the anti-pattern is WS-* and SOAP. If there had never been SOAP, I strongly doubt there would have been a strongly opinionated REST movement.

"Little-r REST" is very little on it's own. It's mostly just common sense as settled by about a decade of trial-and-error. I remember dabbling in PHP-RPC about 10 years ago, and most of the takeaways aren't lightyears from what REST is today.

I write RESTful services, to the best of my ability. Half the tools I use enforce or encourage it.

Confession: I don't understand what the advantages are supposed to be. I want to believe it isn't just arbitrary dogma. I really do.

Applications don't care about the method or protocol a web service is using. Just get the data to and from.

Humans should care about how easy it is to maintain and implement the web services and anything they choose to do to make that goal a reality is good.

Oh, it makes for cute looking URIs, I guess.

I am beginning to gather from this SO post as well as the other HN link to ShareFile, that REST is not something that can be summed up in a paragraph on HN or SO.

This is why the arguments over it are getting heated without seeming to go anywhere. All of the descriptions of REST are met with "That's X, that's not REST. X May be part of REST, but it's not all that REST is".

Turning the SO article into a community wiki is probably the way to go, and allow the discussion to expand until someone who reads it is able to get the concept of REST even though they'll never be able to explain it in a paragraph.

My $0.02. In general, I've found many people describe something as "RESTful" but not actually know what RESTful truly means. Instead, they use it as an acronym to say "A web-based API", which is not necessarily the same thing as RESTful.

The best follow-up question to ask someone is: "What level on the Richardson Maturity Model is your RESTful API?" If they can't answer that, they're probably using the term RESTful to describe something else.

Richardson Maturity Model:

    Level Zero Service  - URI API. Usually just POST. SOAP, XML-RPC, POX.
    Level One Service   - URI Tunneling via URI Templates. GET/POST.
    Level Two Service   - CRUD (POST, GET, PUT, DELETE). Amazon S3.
    Level Three Service - "Hypermedia as the Engine of Application State" (HATEOAS).

HATEOAS is the most complicated. Imagine you're browsing the internet. You go to a webpage, and it loads with lots of text, links, images, and videos. You can interact with it, click on links, watch videos, submit a form, and go elsewhere. You have no idea what appeared on the webpage until after you visited it, and the next time you visit it might change entirely. The link might become broken and you get 404'ed, or you need a username/password otherwise you get 401'ed. HATEOAS is similar to that, but instead of a "person" browsing a "website", it's "client software" browsing "XML/URIs/Resources" received from a server API.

REST is not easy to understand or explain, as it entails learning about many different concepts, ideas, and custom-building something based on them. This is probably why there's no single-sentence which easily describes REST. Saying that something is RESTful is like saying something is Drivable. You can drive a car, truck, motorcycle, bicycle, or boat, but they're all very different from one another. There are similar concepts between them, like accelerating, steering, breaking, but how they do each of those things is very different.

A good book I recommend is "REST in Practice" by Jim Webber, Savas Parastatidis, and Ian Robinson (http://www.amazon.com/REST-Practice-Hypermedia-Systems-Archi... or http://shop.oreilly.com/product/9780596805838.do). That helped me grasp what REST means.

In the accepted answer, what's so bad about the "non-restful" approach the author describes? Who cares if I use GET/DELETE/PUT/POST vs putting the "verb" in a query string argument or the name the file that's being called?

I would say the real power is the simplicity of stateless programming. It's easier to debug and easier to code, thus stronger and faster development.

I think a lot of devs assume it just about "using HTTP to its true potential" which is incidental. Other protocols could be implemented in a restful manner.

Producing RESTful applications is more of an art than a science.

There are two key objectives to bear in mind when designing a web app to be RESTful:

- your app should produce client/server interactions which complement the semantics of HTTP. (this makes the interaction visible and helps with intermediate processing e.g. caching)

- expose your application in a way that minimizes the assumptions clients can make about it - aka 'HATEOAS' (this will reduce risk when making changes to your application and therefore improve the evolvability of your application)

Just thought I'd add that a lot of people are raising the issue of discoverability in restful services. From what I have read this is dealt with with three key constraints: mediatypes, link relations and HATEOAS (hypertext as the engine of application state).

Mediatypes provide a standardised way of processing the representations provided to and from a resource (HTML is processed in particular way, as is JSON, as are PNGs, etc). REST has a constraint that requires you use registered mediatypes. On the web, this is the IANA (http://www.iana.org/assignments/media-types/index.html). If you mint your own mediatypes and use them on the public web, they must be registered with IANA for a service to be considered RESTful.

Link Relations again provide a standardised way of manipulating resources. They describe how resources at the end of a link can be manipulated. Examples include the ATOM edit relation, others include the stylesheet relation.

HATEOAS is a constraint that demands that the the client application should move between states by processing the hyperlinks contained within a representation via the relations provided.

There are two things you should pick up from this: a general REST client will not be able to do much with a service without knowing how to process the mediatypes of the representations returned by resources, and will not be able to move between states on the client without understanding how to interact with the service via the relations the service uses. Think about the most common REST clients out there: web browsers. If I mint a new mediatype that represents "a visual representation of a kitten with a comical caption", I cannot realistically expect a web browser to understand how to process this. The knowledge of how to process my custom mediatype must be baked into the web browser, much like web browsers know how to process image/* media types.

Much the same problem exists with link relations. Most of the time Link Relations are defined with a mediatype (think how a web browser must move to the state of processing a stylesheet by understanding that the link rel "stylesheet" dictates that the user-agent must retrive the stylesheet resource by performing a HTTP GET on the linked resource).

RESTful client applications must be able to understand the mediatypes and link relations used in a RESTful web service.

These three separate constraints, constraints that must be adhered to to be considered RESTful allow a REST client to navigate a REST service. The beauty here is that the service may change the url space of a service at any point without breaking a client, as the client knows all it needs to know to safely move around the client application state, as the rest is provided by the service on a per request basis.

As others have pointed out, caching (another constraint) cuts down on the constant round trips that such a setup would suggest, but I'll leave that constraint for another commenter to flesh out :)

Finally, two points: HTTP headers are part of the representation. This means that mediatypes that may at first appear to violate the hypermedia constraint can be made into hypermedia representations via the link header (http://tools.ietf.org/html/draft-nottingham-http-link-header...). So PNGs can link to resources that contain metadata with a link relation such as "meta" (for example).

Second, many people mention the common HTTP verbs but ignore the OPTIONS verb. Calling OPTIONS on a resource can provide a lot of information back to the client about how they can interact with a resource. I've built systems that provide a list of HTTP verbs that a logged in user may perform on the resource, for example. Different users with different roles may be able to POST or DELETE, whilst others would see that they can only GET.

Hopefully this sheds some light on how RESTful services are made discoverable.

There are two aspects to discoverability: A) listing all of the operations, and B) getting detailed method signatures for a particular operation.

A) is a noble idea but so far few people need to automatically discover and consume web services. B is the real issue: something like SOAP was necessary to make RPC possible over the web for typed languages like C# and Java.

REST was a counterargument made by some people coming from a dynamic languages standpoint who really didn't need as much information as the statically typed language people. Its too bad that people have taken A so seriously though and gotten confused or misled (probably deliberately) about what SOAP was for and then tried to make REST into that.

The most convenient and useful API, even over the web, is one that is as close to normal programming as possible. In other words, RPC-style (or some improvement on that like NowJS). That doesn't mean that you can or should forget that you are making remote calls, it just means that you have less other unrelated plumbing to think about.

If you want to do RPC in a dynamic language over the web, NowJS is your model. The problem is that dynamic languages and statically typed languages have different requirements. I don't think that either SOAP or REST are a good solution to making the two styles work together on a web RPC. I think we need to work on that more.

I guess one more thing complicating this is the fact that most APIs (just like most software systems in general) are in fact dealing with the standard create, read, update, delete operations on data, with some variations. Batch updates are the most common variation, which you could actually easily extend the CRUD model for. The thing is, you almost always have important deviations from that where the CRUD model doesn't fit. But regardless of whether you are doing CRUD or something else, you still want your API to be as simple and normal as possible and that means RPC.

Maybe as some point we can focus more on languages or frameworks that better integrate the CRUD concept and things like calculated fields and aggregation, and transparently handle tasks like persistence and shared state.

Just about all of the programs I write need to persist their data and transmit/share their state. Maybe we want a semantic data oriented networking programming system (or more of them). This would be inspired by dynamic languages like JavaScript but necessarily incorporate some kind of typing more integrally (inferred?).

Maybe just start with NowJS, bake in some kind of CRUD generation based on nested schema definitions, put that on the server, add a way to indicate that operations need to be batched (for transactional consistency and practical network performance) and make the nice MongoDB criteria and now aggregation stuff baked into the client-side also. That would be cool (much cooler and more useful than me thinking or caring about HTTP PUT or DELETE).