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.

Your straw-man interpretation is a scam.

The crappy silverlight app is badly designed and the performance issues you were seeing can be optimised away trivially. (create a new composite resource which can represent the entire tree in one go). That is nothing to do with REST.

"the #1 delusion in distributed systems is that you can compose distributed operations the same way you compose function calls in a normal program" - This is exactly what REST addresses as a style.. i.e. REST is not RPC.

Latency is another issue which REST addresses directly. This is why caching is an explicit constraint.

I have no idea what your point is re: security, sorry. Modelling state transitions is not that difficult, many languages have existing tools to help you do this.

For as long as there has been a web, there has been at least one (often more than one) conceptual ideal claimed to be the heart of the World Wide Web. The reality is that the whole system is hacked together. Things that work well tend to be discovered, re-discovered, and perpetuated --- but that doesn't make any of them the web's "underlying architectural style".

I tend to buy the idea that REST-ish-ness makes for better, clearer, more usable APIs than RPC. But I also think REST needs to win on the merits, not by waving some imaginary "REST is the web" flag.

That said, starting with the Apache web server, Roy had a lot of control with its architecture and approach to supporting particular HTTP features, using his mental model of the "Web's architectural style" to guide it. After 2000 and the thesis, there are many people that started implementing their clients and servers with the style as a philosophical guide.

The style also tends to be widely misunderstood and buzzword-ified, which is scammy.

The architecture of those interactions has remained fairly stable over the past 15 years, even specs that route around REST like WebSockets are trying to at least adopt the HTTP upgrade & tunnel connector (HTTP CONNECT) to ensure it integrates consistently with the style.

afaict, REST is (right now) the undisputed way to interpret the web's architecture.

Do you disagree with any of it? I might be wrong, so a specific disagreement would be interesting.

An appeal to authority: less so.

Yes it is a post-rational analysis of the web.. yes the web was not 'designed' - it evolved.. but do I think, because it evolved, that means it doesn't/can't have an underlying architectural style? no I don't. Do I think Fielding's analysis is sound? yep - and so do most others who have read it (which is a lot of people).

There is a big missing part of the dissertation though - it doesn't go into much detail about hypertext. Apparently Fielding had intended to include it but just ran out of time.

The web of 1995 clearly did not work the way Fielding describes REST.

That doesn't make REST bad, but it does mean you have to advocate for it on the merits, not by waving a flag.

All of the elements he describes in the thesis were deployed by 1994 and codified in the first internet draft for HTTP 1.0: http://tools.ietf.org/html/draft-fielding-http-spec-00

I am generally in agreement that it's best to advocate REST on the merits, but I also think you may be making light of the constant barrage of attacks against the Web architecture through the 90's (with CORBA) and early 2000's (with SOAP) that were defended against by a small core of people, some of whom (Mark Baker) did so at great personal and health expense.

There's a reason people wave the flag - we can't keep arguing complicated topics from first principles if we are ever going to progress.

Regardless of what the RFC says, the CGI interface that provided the foundation for the original wave of web apps was just a series of getenv()'s. It was absolutely not the case that web developers in 1995 were careful to make sure that they represented state consistently or provided discoverable resources. Then as now, most web applications (and APIs, where they existed) were black boxes with parameters defined by expediency.

Also, even Fielding doesn't claim that RPC interfaces are wrong. He seems to have a much bigger (and more reasonable) problem with people pretending that RPC interfaces are REST. There are plenty of interfaces that make just as much sense in RPC as they would in REST; it's not unlikely that there are plenty of them that make more sense expressed as RPC.

I also don't understand the emotional appeal. CORBA vs. REST isn't a moral issue; people who sacrifice their health to make sure we're not using SOAP have their priorities screwed up.

(Thomas, please, btw).

I would actually think Roy (and the actual elite that built HTTP in the 90s) would agree with you on your first point - he defines REST, but that doesn't define the Web, which is hundreds of thousands of scrappy applications. REST was intended to cover the common case of the Web so that the standards themselves will be optimized to the common case. The "self appointed" elite are wrong to suggest that REST is the Web, but to me it's just as wrong to suggest that REST doesn't provide a useful abstract model of what makes the web work.

Regarding CGI, yeah, it was a hack, and it worked. But look at how website design evolved -- sometimes those websites sucked because they changed URIs all the time breaking bookmarks, search engines, etc. These practices weren't thought of in academic terms, no, but the point is that there was a theory underlying what emergent properties made websites good and popular (stable URIs for example, which led to better search, and bookmarking), which led to mainstream aphorisms like "cool URIs don't change" in the 97-98 timeframe. This was eventually codified academically in Roy's thesis a few years later. My point is that this wasn't completely accidental, there were people actively advocating "good practices" in the 90s, even without a formal published theory - it was informally understood by those who were on the mailing lists.

And I agree, RPC isn't wrong, the point is that it is fundamentally flawed approach if your goal is interoperability at a global scale. If you want client A to talk to server B, have at it, just don't call it REST or assume you'll get the desirable properties. Many so-called REST APIs aren't globally interoperable due to this conceptual baggage, but some are better than others.

As for the emotional appeal, my point is... these debates have been discussed ad nauseam for nearly 15 years, with many cases involving personal sacrifice (justified or not). Debating on the merits is fine, but having ot go back to first principles every 5 years for a new generation means we are just spinning our wheels. That's why there often is appeal to history or authority. i.e. "Read the mailing lists, they're archived", etc. That's not a great situation, I admit. But most new technologies have traditionally had a "vendor engine" behind them pushing marketing, training, books, etc. to perpetuate the meme. That seems to be less common with the open source / internet vendor world, or maybe it's just that REST is still too new and misunderstood.

Why is it significant that the web evolved between 1995 and when Fielding defined REST?

To most people, the paper is well-reasoned and REST is observable in the web where the constraints appear to produce their supposed beneficial effects. I think it's reasonable to see REST as the underlying style of the web, and the web has some very beneficial properties (scalability, evolvability) which therefore stand to REST's merit.

This is the problem I face with REST all the time. I have yet to see someone pull this off gracefully. Take the hierarchy Authors/Books/Characters. If I wanted the full list of all Authors, with all Books, with all Characters what are you suggesting I do? Now what if there was another level after that? And after that?

This simple example could work with the use of a 'depth' value which has been suggested. But it doesn't work all the time. Especially when there are forks in the hierarchy and you want to go deeper in one and not the other. Basically I've determined that it seems impossible to have a pure 'model' of your data and an efficient API.

    Take the hierarchy Authors/Books/Characters. If I wanted
    the full list of all Authors, with all Books, with all
    Characters what are you suggesting I do? 

{ "characters": "<uri>", ... }

Doing a GET on the supplied characters URI gets you a list of characters, each with a mixture of relevant properties and a URI for the character itself so you can interact with it directly.

(2) Cacheing is part of the problem as much as it is part of the solution in making reliable apps. Anyone who's actually written AJAX apps knows that you frequently need to use tricks to disable cacehing to get things working right.

(3) As for security, this isn't just state transitions in the Turing sense but could involve numberic ranges and other kinds of variables. Generally code that compares composite objects is the kind of code that hides errors, particularly given the fact that for most languages there is something funky about the equals operator. (This is certainly true about C++, Java and PHP)

If something requires multiple API calls when it could just require one, this points to the the resource being too finely-grained and ill-fitting to the behavioural domain of the client.

The resources attached to URIs do not need to be directly related to the underlying data model implementation. The interface which you provide to a client-side developer should closely match their domain and not just your implementation [2]. Provide useful abstractions.

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

Can you expand on this? I've not run into similar problems myself.

[1] RESTful Web Services correctly inherit and use HTTP as their interface.

[2] http://en.wikipedia.org/wiki/Domain-driven_design

Great point. I think this is where I get hung up a lot. Its just too much work sometimes to try and imagine how people will consume your API. In a perfect world people should have to ability to mash up your data to create any kind of application they want and so we tend to drill straight down to the fine-grained model. It feels easier since we have already figured out that model, now all we need is a URL structure to also represent it.

But, when I explore creating a model which represents the consumer's domain I feel like its really dang close to RPC. Basically I end up slipping the opposite direction I did before. Why not just make every API call have it's own resource representation? FullCatalogWithAuthors might as well be GetFullCatalogWithAuthors.

1: The reason the app in question had to traverse a tree and the principle that the poster probably breached by reorganising.

I hate to defend SOAP, but WSDL does a good job of documenting web services. My jaw dropped when I pointed Visual Studio at Salesforce.com's WSDL file and it correctly created a set of statically typed stub functions for a very complex API... I'm so used to this stuff not working that when it does it's like WOW.

HATEOS addresses just a fraction of what WSDL does.

I suspect that .NET WSDLs (of which this was one) work well with .NET clients - but in that case it's might was well be any proprietary RPC protocol.

Correct me if I'm wrong, but REST discoverability isn't meant to provide machine discoverability, but human discoverability.

That doesn't mean I like SOAP (I don't), but I don't find that this particular critique of it rings true.

So far we've only see a few like AtomPub and its extensions, or the discovery protocol stack (http://hueniverse.com/2009/11/the-discovery-protocol-stack-r...).

The challenge has been, IMO, a programming model that fits the Web, which can then fit into a media type spec or two that adopts it (similar to how HTML was codified for the experience of a web browser). WSDL basically is the procedural programming model, where networked interactions are usually mapped procedure calls. This model a whole bunch of long discussed problems when dealing with wider scale interoperability.

I've tried to outline this challenge in detail in my keynote at last year's WS-REST workshop on the "Write Side of the Web": http://www.infoq.com/news/2011/03/web-write-side

Is WSDL richer and more productive than documenting a bunch of URI patterns for a complex API? I'm not sure about that. WSDL tends towards code generation for very specific sorts of interaction scenarios, and ignores things like cacheability of results, the safety or idempotency of the request, and the ability to access data across endpoints without a lot of a priori knowledge in the client. Many of those properties are easier to implement with plain HTTP used in a RESTful manner.

So, if I provide a URI that means "a list of links to various resources with interesting data", those linked URIs can be bookmarked (they're persistent), but the original URI has every right to change the links later on if it thinks there are more relevant ones (e.g. newer, more relevant, etc.). Think of how a news site's main page changes with "Top News Stories", for example. That doesn't mean the older URIs it pointed yesterday to are necessarily bad.

For a RESTful machine-to-machine interface, this HATEOS approach is arguably one of the more effective ways to do extensibility and versioning: http://www.mnot.net/blog/2011/10/25/web_api_versioning_smack...

RPC gives server parameters and asks it to actually do something, whereas REST asks for a representation of some resource.

Not that I agree with that particular architecture, but my first question is: why did the Silverlight app discard the knowledge that it had worked hard to discover? If a technician spent 20 minutes figuring out how a thing worked, would he just willfully forget it?

> 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 whole idea behind object oriented programming is that you don't compose functions, you let objects pass and respond to messages and record their observations (state).

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

Meaning that the "objects" observe and record information about the world and respond appropriately based on their (recorded) observations. Interetingly enough, Alan Kay said that TCP was one of the few things that was designed well from the start. (Or maybe it was IP, I'm trying to find a source.)

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

That's a good point about security rules and state transitions but I don't understand the problem, objects are supposed to be responsible for some kind of state and we should let them worry about their state transitions. Can you provide and example of error prone code that needs to compare the before and after state?

------------------------------------------------------------------------------------------------------------------------

REST isn't a scam but the tooling (programming languages and frameworks) just aren't there. Our languages, even the so-called object-oriented ones are still based around the idea of calling procedures. REST works when you're dealing with objects that respond to messages, not imperatives.

Alan Kay made the case for something like REST in his 1997 OOPSLA keynote[1] (preceding Fielding's dissertation by 3 years). The idea is that in really big systems (distributed over space and time), the individual components need to be smart enough to learn how to interact with the other components because the system is simply too big to accomodate static knowledge (and I say this as a fan of statically typed languages).

[1]http://video.google.com/videoplay?docid=-2950949730059754521 at 43:00

You mean GET PUT, POST, DELETE ? This is my criticism of REST. If we transform all our processing objectives into nouns which we can address with these verbs, we will arrive straight away in the http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom...

> The whole idea behind object oriented programming is that you don't compose functions, you let objects pass and respond to messages and record their observations (state).

But this was SOAP in the first place?

The point of all of this is interoperability. Communication requires shared understanding, which is impossible if everyone invents their own nouns and verbs at whim.

In fact, REST specifically lets systems grow organically since each object never assumes knowledge about either state or state transitions, all knowledge is contingent and empirically discovered.

Okay. I'll let Alan Kay argue the exact same point then.

http://video.google.com/videoplay?docid=-2950949730059754521

The whole video is worth watching but the relevant part starts at 43:00. This video was made three years before Fielding submitted his dissertation.

(note: this isn't an appeal to authority fallacy since he's making an actual argument.)

But now that I think about it, I realize why people have a hard time understanding REST. It's not a "design" constraint any more than OOP is. It's an implementation constraint. In the case of OOP I think people confuse those notions because they conflate designing a system with designing class heirarches. But OOP doesn't have anything to do with classes. A system is object oriented when the state is private, objects communicate by passing messages and methods are late-bound. Similarly, you don't really design a system to be RESTful, you simply commit to the idea that you never know — a priori — what methods will be available on a resource. You determine them by asking the object and those methods are only valid as long as the cache-control header says they are. Just about everything else follows from that.

> the point is that the network imposes limitations and you often need a domain-specific design to get around them

That's why REST emphasizes caching, stateless communication, the appropriate use of status codes, and the appropriate use of VERBs (idempotent vs non).

> for example, HTTP is awful for soft real-time applications.

I wouldn't write an OS kernel in Ruby either.

Your attempt to enforce some dichotomy between design and implementation is hopelessly misguided.

>That's why REST emphasizes caching, stateless communication, the appropriate use of status codes, and the appropriate use of VERBs (idempotent vs non).

These don't solve the major problems. If I want caching I can trivially implement it myself. It's a useless thing to implement at the architecture level.

Similarly for idempotency etc. It's all a huge academic wank. An appropriately designed protocol will solve all these problems without the constraints.

>I wouldn't write an OS kernel in Ruby either.

What smug yet clueless response. You're begging the question.

I'm frankly bored of talking to someone who knows nothing about protocol design, but defends HTTP as a "proven" technology. It clearly isn't, it fails on many levels, and the whole web stack is completely fucked. Good day.

Legions of computer scientists and computer engineers disagree with you. Caching is fundamentally an architectural concern.

>I'm frankly bored of talking to someone who knows nothing about protocol design....

Please point to your widely commercially deployed protocols before accusing others of ignorance.

> ..but defends HTTP as a "proven" technology. It clearly isn't, it fails on many levels, and the whole web stack is completely fucked. Good day.

You've demonstrated an astounding lack of respect for pretty much everyone on this topic here, and I'm finding it incredulous myself to have to tolerate the amount of bitterness being emanated from you. Why are you participating here it all, unless you just want to tell us we're all clueless, and you can feel superior?

[1] The Smalltalk variety of OOP which is about encapsulation, message passing, and extreme late binding.

A "well documented protocol" (binary or not) by definition is interoperable within a certain context. The question is, how big is the scope of that context?

The point of the Web protocols is to provide a framework for evolving bits of agreement - not "big design up front", except for the essential bits that have proven themselves, or are essential to bootstrap communication. HTTP, MIME, and URI are those essential bits of agreement at the moment. Witness how HTML isn't as essential as it used to be, given the growth of JSON APIs and mobile native apps.

As for REST, I'm sure it's nice for some things. However, if you think interoperability is going to magically spring out of it you're ignoring the lessons of XML, which that having an (ostensibly) human-understandable format is not going to magically allow machines to become more interoperable. All it will do is allow people to make bad guesses about the meaning of documents instead of reading the documentation.

Similarly, to suggest that HTTP hasn't proven itself (compared to what?) or that "innovations" of the web existed decades ago (really!?) is nonsensical to me. It's the most widely deployed application protocol on Earth. It handles billions of dollars of transactions.

You claim the web is unreliable. I think that's a layer error. The issue is that networks are unreliable. That's not something one can paper over.

>Similarly, to suggest that HTTP hasn't proven itself (compared to what?)

Compared to writing your own protocol that is appropriate for your application. The fact that people think HTTP is good enough has meant the browser has only recently acquired the ability to have a proper duplex channel without polling. Sorry, but that's just pathetic.

>or that "innovations" of the web existed decades ago (really!?) is nonsensical to me.

Name one thing that can't be constructed more efficiently and flexibly on the desktop, aside from web links.

>It's the most widely deployed application protocol on Earth. It handles billions of dollars of transactions.

So what? Because it's popular that means it's good? I used to be dismissed because as long as 7 years ago I was telling people we needed sockets and proper client/server in the browser. Now I'm getting the last laugh as I watch the browser vendors take decades to slowly do this stuff. At each step, it is labeled "innovative" and interesting and hyped up beyond all comprehension. The progression of this trend is retarded by the insistence of inventing stupid premature optimisations like caching as a basic architectural feature.

>You claim the web is unreliable. I think that's a layer error. The issue is that networks are unreliable. That's not something one can paper over.

Then you're ignorant of the potential of low-level protocol design. Sorry, but I absolutely can tailor my network protocol to my particular application. The web takes the position that everyone should use HTTP. It is a terrible protocol for many things. How are you going to design your soft real-time applications using HTTP? The answer is you can't, because it is impossible to get the right guarantees. HTTP has only "proven itself" in the same sense that Windows has; it was good enough at the time, so now it's blown up and everyone's using it. So what? I want more.

Firstly, they were not both attempts at systems interoperability for a huge domain. XML was about building a specific format. REST is an entire architecture. It's the difference between designing a car and designing the interstate freeway system.

Secondly, let me get this straight. It's been a long standing goal for decades of both academia and industry to build a global scale interoperable distributed system. That this was done with distributed hypermedia, bridging languages, graphics formats, operating systems and computer architecture is not "new and special"?

> [HTTP isn't proven] Compared to writing your own protocol that is appropriate for your application.

Most hand-written protocols suck.

It's also these days rarely required given the strength of existing application protocols, and the widespread desire for interoperability, but clearly you don't value with that.

> The fact that people think HTTP is good enough has meant the browser has only recently acquired the ability to have a proper duplex channel without polling. Sorry, but that's just pathetic.

No, that's not pathetic, it's a consequence of the economics of scale. It is very difficult to economically sustain an event-driven internet scale system. e.g. http://roy.gbiv.com/untangled/2008/economies-of-scale

> Name one thing that can't be constructed more efficiently and flexibly on the desktop, aside from web links.

Firstly, most of what we do with computers these days is communication, processing, and commerce over web links.

Secondly, most data management applications are vastly more flexible, interoperable, and efficient with web technologies than they were with desktop technologies such as Access or Powerbuilder.

> I used to be dismissed because as long as 7 years ago I was telling people we needed sockets and proper client/server in the browser. Now I'm getting the last laugh as I watch the browser vendors take decades to slowly do this stuff.

I wouldn't be laughing yet. WebSockets is a sideshow that's not going to change a whole heck of a lot of how web apps are built. There will be interesting uses for it, but it's ultimately limited in scale and scope due to a lack of shared design constraints.

> Sorry, but I absolutely can tailor my network protocol to my particular application.

Sure you can, but you're basically making a value judgement that interoperability is of no concern to you, and that reuse is of no concern to you.

I mean, why use TCP, when we can just roll our own transmission layer on UDP? There are times that's needed (RTP), but we get a lot of productivity benefit with TCP.

> HTTP has only "proven itself" in the same sense that Windows has; it was good enough at the time, so now it's blown up and everyone's using it.

Sorry, that's just nonsense. The web has been a vast success story for global interoperability, and that can be directly attributable to the design constraints embodied in the main protocols of the web (HTTP, URI, and MIME).

I highly suggest you read Roy's thesis and reflect before postulating your opinions on this subject, since you really don't seem to have any appreciation for the amount of thought and engineering that went into the Web.

I would be more than happy to read to any sources you may have of what other protocols and/or techniques are clearly superior to the Web protocols (presuming I retain interoperability at scale as a major value).

Method missing is in my book completely differrent from Page Not Found. Method != Resource.

This isn't pedantry, the result of a request (message) for an object is the representation of the state of that object. 404 is an application level error saying that the remote object has no method for dealing with the message. Obviously that also means it's not going to be able to send you a representation of the state of some object that was the response to the message.

Also, REST doesn't preclude having a static list of messages. It's just prescribes that it's up to the remote object to report the messages to which it can respond and up to the local object to decide to statically record those messages somewhere so that it doesn't have to unnecessarily ask again. The remote object can even helpfully tell you when that list of "procedures" might expire so that the local object can know when it should ask again.

For "I won't use this method on the resource you specified" you need a 405

For "I do not understand this method" you need a 501.

Now, I don't really think it's worth arguing and I can certainly see why you would use those codes that way but for me I've always treated 4xx codes as being about the resource/object and 5xx codes as being about the object's environment (i.e. the server). Said another way, I treat 5xx as runtime exceptions and 4xx as application error messages.

I'd never write code that returned a 5xx error from within my application for instance, that's for the server to handle.

405 means that the object knows about the method but for some reason won't allow you to call it. In OOP parlance, you would use it if someone tried to call the "Drive()" method without first calling the "StartEngine()" method. Indeed, RFC-2615 prescribes that you return a list of valid methods if you return a 405.

Thus, the only real candidates for something like METHOD_MISSING are 400 and 404. But 400 seems like it's for something that the application can't even understand. Like if the client is using some weird encoding in the host headers or something.

Of course enclosing a message in a SOAP envelope does not preclude RESTfulness. If the set of messages to which an object responds is a function of its current state then it's RESTful (or at least lead to a RESTful design).

REST isn't even about discoverability. That's just a natural consequence of calling methods that might only exists when an object is in a particular state (i.e. the object creates the methods at runtime).

The difference between REST and (usual) SOAP is the difference between late-binding and "extreme late-binding"[1]

[1] http://www.google.com/#sclient=psy-ab&hl=en&source=h...

What I meant to say is that in REST, the set of messages to which an object will respond is a function of the object's current state. With SOAP, a URL endpoint always takes the same set of messages (until the code is rewritten or something).

This is why clients should cache REST requests.

If you make a GET request against a REST interface then you should cache the results of that request and note the datetime you made it.

If you need to make a subsequent request against the same resource then you can first make a HEAD request to get only the headers. By comparing timestamps you can see whether or not the resource has changed since you last accessed it.

If the REST interface is appropriately designed then the "last changed" value will propagate upwards from the leaves of the tree towards the API root. So caching the results of requests can save you from making an immense number of requests.

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

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.

  {
    index: function (req, res) { ... }
    create: function (req, res) { ... }
    retrieve: function (req, res) { ... }
    update: function (req, res) { ... }
    delete: function (req, res) { ... }
  }

Further, it is built on sound principles such as, you can't destroy or change anything using GET, you can issue requests other than POST any number of times and nothing will go wrong.

Other things like using HTTP headers to decide in which format the consumer wishes to consume the resource, HTTP status codes for error handling, and HATEOAS, gives me the feeling of working with the system instead of building cruft.

I argue that REST in fact makes it easier "to maintain and implement the web services". YMMV.

* A RESTful API is discoverable. With no background knowledge, a client can do a GET request on the root URL to get a list of resources with URLS. It's easy to dive right in and quickly figure out what is available.

* Developers understand HTTP. REST is essentially just HTTP, and we already understand HTTP. REST means the API developer doesn't need to waste time and energy (badly) reinventing/re-implementing what HTTP does on top of HTTP; and the client doesn't need to waste time and energy learning a bunch of ad hoc protocols.

* Our tools understand HTTP. Just about every client language/framework on earth already understands HTTP. Without jumping through any extra hoops, a client working in Python or Ruby or C# or Java or JavaScript or PHP or even VBScript can execute an HTTP request on an API resource and understand the response.

* REST keeps us honest. A RESTful API architecture forces the API developer to be clear about what is a resource and what methods clients can execute against each resource. This makes for a better-organized, more orthogonal API.

So is SOAP.

>> Developers understand HTTP

SOAP runs on just about anything including HTTP or even SMTP.

>> Our tools understand HTTP

SOAP doesn't care what the clients or servers are written in or run on.

>> REST keeps us honest

I disgree, you can change something in a JSON packet and the client will only know it broke when it's run. With SOAP, if your client uses a compiled language then you as a developer will know first before you give it to a customer to run, you can fix it then.

No it's not. In theory, you can just consume the WSDL and have all the methods available to you, but in practice, there are huge and unbridgeable issues with interoperability. A C# SOAP client will have trouble consuming a Java WSDL, and so on.

> SOAP runs on just about anything including HTTP or even SMTP.

SOAP runs on top of HTTP but merely uses HTTP as a tunnel. All the stuff that should be in HTTP - the resource, the method, the data - is inside the XML envelope.

If you want to consume a SOAP web service, expect to get your hands dirty.

> SOAP doesn't care what the clients or servers are written in or run on.

In theory, no. In practice, interoperability is by no means a given.

> you can change something in a JSON packet and the client will only know it broke when it's run.

That's not really what I was talking about, but if you make a breaking API change in any system, you should have a way to do it so clients aren't caught flat-footed when their app breaks.

Neither REST nor SOAP inherently solves this problem, but REST does allow for custom media types that include versioning.

I have had no issues getting a C# client on Windows to work with a Java SOAP server running on Tomcat using AXIS.

I even have an Android client talking to that SOAP server with no issues.

>> In theory, no. In practice, interoperability is by no means a given.

That's because it's contract driven, with REST any changes on the server in the API will not break the client's compile so you won't know it broken until the customer calls at 2 AM. Unless of course you have 100% unfailing testing processes.

>> if you make a breaking API change in any system, you should have a way to do it so clients aren't caught flat-footed when their app breaks.

Cool yes right, SOAP.

>> REST does allow for custom media types that include versioning.

If REST ever gets to that level of specification we will have SOAP.

This is something I have a hard time understanding. Your hypothetical generic REST client will have a hard time understanding my HATEOAS, discoverable, fully REST-ified service, if it has no idea what the service is supposed to do contextually. If my 'blog' resource has links to 'metadata' and 'related' things, without knowing what those are, how does a 'generic' REST client do anything with them?

How is that significantly different than SOAP?

I would love to see an actual example of the difference, rather than abstract discussion, as this is the point I have the hardest time understanding.

The Facebook Graph API is a great practical example of this ease of use in practice: https://developers.facebook.com/docs/reference/api/

You're quite right that things like "related" and "metadata" link relations mean nothing if you don't know what those mean - they are hooks for future bits of agreement. The difference between REST and WSDL in the long run, in my opinion, is the practical composability of small bits of agreement (or specs). The Web Services stack (SOAP, WSDL, WS-*) has had a very difficult time composing a bunch of specs together as the kernel of their agreement is basically the XML Infoset. With the RESTful Web, the kernel is HTTP, URI, and MIME (for now), which has endured a number of extensions (Flash, HTML5, Atom/RSS, etc.) and evolutions (the rise of mobile devices).

Actually, prior to REST, most developers didn't even know about PUT/DELETE/etc. which are key operators that RESTful services are supposed to exploit.

Most developers also have shockingly poor understandings of all kinds of aspects of the HTTP protocol (headers, which ones are important, semantics of the various verbs, pipelining, multipart MIME/server push/etc., they typically know at best a handful of error codes that make sense in a RESTful context...).

Where is that specified for REST? I don't remember it from Fielding's paper, and I've seen plenty of self-described RESTful services that aren't even remotely discoverable.

More than that though, service discovery is a very old concept and not anything new that REST brought to the table.

I'll be the first to acknowledge that the REST specification, at least in Fieldings Ph.D. dissertation, is unfriendly. Here's Fielding trying to explain what he meant:

"A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations."

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

In general, this goes by the tortured acronym HATEOAS:

https://en.wikipedia.org/wiki/HATEOAS

And REST advocates wonder why people have a hard time understanding it.

> I've seen plenty of self-described RESTful services that aren't even remotely discoverable.

You're right. Most services that call themselves RESTful aren't. I think the REST movement itself deserves a share of responsibility for how widely REST is misunderstood.

> service discovery is a very old concept and not anything new that REST brought to the table.

What REST brings to the table is the ability to discover your way through a service with no required background knowledge other than HTTP - which will be the transport protocol in (almost) any case - and some common media types.

Though generic client isn't going to know really what to do with your service. Aside from performing basic CRUD operations, a generic client would have no understanding if what any of it actually means. But, for example you can use code libraries that are designed to work with REST services in your client and not have to write as much boring "plumbing" code.

This is where hypermedia comes in. A rich set of standard media types allows your generic client to do useful things without knowing about any particular service.

I think this doesn't seem that important because we still code each client against particular API, but we could adopt true uniform APIs - by not only using the HTTP methods and following HATEOAS, but by also standardizing on data formats that are widely adopted¹ - we would be able to write much more generic clients that could work with different APIs, perhaps even with ones not considered by the developer, without wasting hours upon hours writing code against each service.

¹ No, JSON isn't a standard data format, but more a standard serialization format. You still have to manually code against each service's response types.

With SOAP, you know everything, just ask the server for its WSDL.

The solution was to have Suds re-route specific URLs to resolve correctly. The fact that Suds is designed this way is testament to his common this problem is.

Yes, you can get HTTP servers that don't respect the safety of Get, but it's a much less common issue.

My SOAP web app runs fine, my Android test client also hits it with no complaints.

My Apache server can be hit with both HTTP and HTTPS which lets me use Apache to handle certificate management while I cna run any type of app server on localhost that I want.

So far no issues with this scenario. I used this for a contract I was just on and it also worked fine for both the SOAP and REST clients.

Beyond good common-sense things like this, REST seems to involve a lot of people yelling about whether something is or is not REST.

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.

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.

A person browsing a web site is not "like" HATEOAS, it is the canonical example. The client software, in that case, is a web browser.

REST itself does not concern itself with the protocol you use. Theoretically you could build a REST protocol over HTTP that does not use HTTP verbs, using it as only a transport layer. Though I'm not sure what you would gain by implementing a REST protocol over another REST protocol.

Pragmatically, if you choose to use HTTP, you need to think about the infrastructure that exists. Each verb comes with a very specific meaning, and systems like proxies and other software that come between you and the client will act in different ways depending on which verb you choose. To meet the goals outlined in the REST dissertation, you need to be aware of those behaviours.

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.

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)

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.

Most of the examples I've seen extolling the virtues of HATEOAS use XML, specifically the <link uri="..." rel="..." /> element. That's great for a single media type (XML), but what about JSON, which is by far the dominant media type used in RESTful APIs?

A google search for "hateoas json": https://www.google.com/#q=hateoas+json&fp=1

reveals...a bunch of people asking how to format link relations in JSON, without a definitive answer that I can see.

HATEOAS and discoverability are principles that sound great in high-level discussions but I have yet to see them implemented in a meaningful, helpful way.

Anyhow, you seem quite knowledgable on the subject so perhaps you can enlighten me. Usually it's my own ignorance/obstinateness that's to blame rather than a flaw in the concepts themselves...

You can use both, and simply use the Accept HTTP header to determine which format you want. It gives you both discoverability of HTML (with <a>), and data transfer that is easy to parse.

HTTP Response:

  HTTP/1.1 200 Ok
  ...
  Link: <http://example.com/some-resource>; rel="edit";
         title="Edit some resource"
  Content-type: application/json

  {"prop":"val"}

I agree, I havent seen a "true" RESTful service either, except for very simple examples. As others have noted, REST is quite a difficult architectural style to summarise in a few short pithy statements, which leads a lot to the confusion on implementation. I also think that the fact that the architectural style is defined by constraints, which traditionally flies in the face of all previous architectural styles I have seen, which emphasise features and what you CAN do. REST is about what you DONT do. Its these restrictions that combine to make something very powerful, flexible and scalable. Think chess: its a stupid game with a board limited in size, the pieces all move in complicated but specific ways. It cant possibly be an interesting and deep game with all these constraints!

If you are interested in discussions on the subject, I recommend joining the rest-discuss mailing list on Yahoo Groups. Sure the conversation veers into hand-wavy, ivory tower territory, which can be forgiven seeing as the discussion group is for exactly this, but you get some very comprehensive and detailed explanations. Definitely search the archives because a lot of stuff has been answered in great detail before. Roy Fielding even pops on sometimes to correct a few points, and you dont get much more authoritative on the subject than that :)

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