[ademarre]

The problem with REST is that many (I dare say most) who think they are applying it really aren't.

I think this is quite relevant: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

What sets REST apart from RPC is the Hypermedia-as-the-Engine-of-Application-State principle (HATEOAS). With HATEOAS, interaction semantics are removed from URIs and defined in terms of link relations. This decouples clients from URIs; very valuable.

ADD: To equate REST with CRUD overlooks HATEOAS completely. Simple CRUD solutions work on resources that have already been identified, but HATEOAS adds resource identification/addressing and discovery in a very maintainable way.

[steveklabnik]

While I agree with you that that's certainly an interesting part of the split between RPC and REST, you might be curious to know that Fielding doesn't think so.

> What makes HTTP significantly different from RPC is that the requests are directed to resources using a generic interface with standard semantics that can be interpreted by intermediaries almost as well as by the machines that originate services.

http://www.ics.uci.edu/~fielding/pubs/dissertation/evaluatio...

[ademarre]

Interesting, thank you; but in that quote isn't Fielding actually comparing RPC and HTTP, not REST?

[steveklabnik]

Yes, you're right, I was being a bit sloppy there. The Uniform Interface (and Layered System) is one of the ways in which HTTP does follow RESTful principles, though, so the thrust is still the same.

[ademarre]

Agreed. But I think it's a stretch to conclude that Fielding doesn't think the hypermedia principle is an important distinction between RPC and REST:

From his blog post I linked to earlier, titled REST APIs must be hypertext-driven [0]:

> "I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.

"What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint?"

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

[superdude264]

I don't understand how it's possible to program to a true REST service given his final bullet point and one of his comments:

> 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. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]

> When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions. [...] Hypertext does not need to be HTML on a browser. Machines can follow links when they understand the data format and relationship types.

If you're only supposed to start with an initial URI and there is no out-of-band communication, how is an automaton supposed to know what links to follow to reach the desired information? A person can do this by reading, reasoning about what they read, then following the appropriate link. Writing an automaton that can reason about anything that can fall under the initial URI seems equivalent to writing some kind of artificial intelligence.

[prawks]

The key is:

> [a] 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)

There is out-of-band "communication" in that the client and server agree on these media types and how to use them.

The following article does the best job I've seen at illustrating a truly RESTful service:

http://www.infoq.com/articles/webber-rest-workflow

The <next> node in the response to the order POST is one such example.

[superdude264]

Great article. If I'm understanding it correctly, it seems like the advantage comes from mapping your domain actions to the standard HTTP actions on each domain object. Once this is done, your API is simply the media types and the interaction with your service can be done through well-understood HTTP actions rather than learning a bunch of method calls as in an RPC approach. Correct?

[pfraze]

There are common standards for links. I think you can do reasonably well by supporting 2 or 3, though I'd prefer the world moved to the Link header. The others are html (<link>, <a>) json-hal, jsonld, etc. Regarding the process:

Links include metadata and types (the "rel" attribute). You can think of the full set of given links as an index. To search this index, you scan for reltype first (since that carries semantics and guarantees behavior) then check the other metadata attrs as needed (eg type=text/css). The only knowledge you embed then is published under the reltype specs.