Is That REST API Really RPC? Roy Fielding Seems to Think So

Question

A large amount of what I thought I knew about REST is apparently wrong - and I'm not alone. This question has a long lead-in, but it seems to be necessary because the information is a bit scattered. The actual question comes at the end if you're already familiar with this topic.

From the first paragraph of Roy Fielding's REST APIs must be hypertext-driven, it's pretty clear he believes his work is being widely misinterpreted:

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.

Fielding goes on to list several attributes of a REST API. Some of them seem to go against both common practice and common advice on SO and other forums. For example:

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

• A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). ...

• A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. ...

The idea of "hypertext" plays a central role - much more so than URI structure or what HTTP verbs mean. "Hypertext" is defined in one of the comments:

When I [Fielding] 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. Hypermedia is just an expansion on what text means to include temporal anchors within a media stream; most researchers have dropped the distinction.

Hypertext does not need to be HTML on a browser. Machines can follow links when they understand the data format and relationship types.

I'm guessing at this point, but the first two points above seem to suggest that API documentation for a Foo resource that looks like the following leads to tight coupling between client and server and has no place in a RESTful system.

GET   /foos/{id}  # read a Foo
POST  /foos/{id}  # create a Foo
PUT   /foos/{id}  # update a Foo

Instead, an agent should be forced to discover the URIs for all Foos by, for example, issuing a GET request against /foos. (Those URIs may turn out to follow the pattern above, but that's beside the point.) The response uses a media type that is capable of conveying how to access each item and what can be done with it, giving rise to the third point above. For this reason, API documentation should focus on explaining how to interpret the hypertext contained in the response.

Furthermore, every time a URI to a Foo resource is requested, the response contains all of the information needed for an agent to discover how to proceed by, for example, accessing associated and parent resources through their URIs, or by taking action after the creation/deletion of a resource.

The key to the entire system is that the response consists of hypertext contained in a media type that itself conveys to the agent options for proceeding. It's not unlike the way a browser works for humans.

But this is just my best guess at this particular moment.

Fielding posted a follow-up in which he responded to criticism that his discussion was too abstract, lacking in examples, and jargon-rich:

Others will try to decipher what I have written in ways that are more direct or applicable to some practical concern of today. I probably won’t, because I am too busy grappling with the next topic, preparing for a conference, writing another standard, traveling to some distant place, or just doing the little things that let me feel I have I earned my paycheck.

So, two simple questions for the REST experts out there with a practical mindset: how do you interpret what Fielding is saying and how do you put it into practice when documenting/implementing REST APIs?

Edit: this question is an example of how hard it can be to learn something if you don't have a name for what you're talking about. The name in this case is "Hypermedia as the Engine of Application State" (HATEOAS).

Stoker

John, Rich is just explaining the change in mindset he had. There's nothing subjective or argumentative about it. Vote to keep open - the is one of the better questions tagged 'rest' I've seen on SO. – Chalco

Keith, "explaining the change in mindset" is something he should do in his blog, not on SO. – Pharisaism

He's not explaining his change in mindset, he's asking if his understanding is accurate. – Scheel

Excellent summary. I learned more from this question than from most answers. – Lengthways

Answer 1

I think your explanation mostly covers it. URIs are opaque identifiers that should, for the most part, not be communicated beyond the bookmark URI that is used by the user agent to access the app.

As for documenting, this question has been done quite a few times. You document your media type, together with the hyperlink controls that it contains (links and forms), and the interaction model if you so wish (see AtomPub).

If you document the URIs or how to build them, you're doing it wrong.

Significance

Is this still true? There are API response specs like Ionspec which have made these URIs as part of the response intentionally. – Sumerlin

Yes they have. At that point it's a question of figuring out if those documented URIs are just entrypoints to the application, which are guaranteed to stay (a few of those are not uncommon and pretty useful) or if, because people want code generation, those are embedded from a spec straight into the code, preventing the server from letting the client know about how it can do things. If the client thinks it knows due to that contract, you're not in hypermedia, you're into the modern day openapi soap model, with the same issues you'd have encountered with that 18 years ago. – Significance

What is true is that many API documentation languages have spun up in the last 11 years, but the fundamentals have not change. I believe the value in discovering those links, or at the very least URI template discovery, is in building reusable generic client code that can dynamically use those, allowing many implementations on the server side to reuse the same client code. URI embedding continues to make harder such scenarios, but if you use those formats, you tend to tightly couple a generated client from those specs, so you've already lost that feature. – Significance

"If the client thinks it knows due to that contract, you're not in hypermedia, you're into the modern day openapi soap model, with the same issues you'd have encountered with that 18 years ago." Can you explain what you meant by this? – Sumerlin

Answer 2

Your interpretation seems correct to me. I do believe that Fielding's constraints can be practically applied.

I really would like to see someone publish some good examples of how to document a REST interface. There are so many poor examples, have some valid ones to point users to would be very valuable.

Mattos

Wow. That Resource Model page brought a tear to my eye. Let's hope this starts a trend. – Mattos

It's a shame this is basically the only example of such an API on the web! Worse still, there are no good examples of client code that follows the principle at all (that I have found). – Melodiemelodion

@DarrelMiller But aren't those Media Types too "specific"? It seems to me that their API is truly using only one MIME: application/json, and that the Resource Model are truly the relations. Did I misunderstand this aspect of REST? I have also read one of your SO answers which seems to point out that those "one attribute" contracts should be avoided... – Insecticide

@RichApodaca Your link has died of dysentery. web.archive.org/web/20170409132237/https://kenai.com/projects/… – Grandpa

Answer 3

I have been looking for a good example of an API written following the HATEOAS and had trouble finding one (I found both the SunCloud API and AtomPub stuff difficult to apply to a "normal" API situation). So I tried making a realistic example on my blog that followed Roy Fieldings advice on what it means to be a proper REST implementation. I found it very difficult to come up with the example, despite the fact that it is fairly simple in principle (just confusing when working with an API as opposed to a webpage). I get what Roy was taking issue with and agree, it is just a shift in mindset to implement properly for an API.

Have a look: API Example using Rest

Electromagnetism

Answer 4

The one exception to giving instruction on how to build URIs is that it is permissible to send a URI template in the hypertext response, with fields to be substituted automatically by the client, using other fields in the hypertext. This doesn't usually end up saving much bandwidth though since gzip compression will handle the repeated parts of URIs well enough to not bother with this.

Some good discussions on REST and the related HATEOAS:

Advantages Of (Also) Using HATEOAS In RESTFul APIs

How to GET a cup of coffee

Scheel

Answer 5

For those interested, I found a detailed example of HATEOAS in practice in the Sun Cloud API.

Stoker

Link is dead. Archive – Exosphere

Answer 6

The thing that most people get wrong is that (at least i think) in the REST world you don't document your "Rest interface", what you document is a media type, independently of your server or service.

Spiroid

Answer 7

I think over the number of years that REST has been out there now, technologists have come to terms with the concept of a Resource and what really is or isn't RESTful.

According to the Richardson Maturity Model, there are 4 levels (0-3) that define how RESTful your API is, with 3 meaning a truly RESTful API, just as Roy Fielding intended it to be.

Level 0 is when you have one entry point URI - like SOAP.

Level 1 means the API is able to distinguish between different resources, and has more than one entry points - still smells of SOAP.

Level 2 is when you use HTTP verbs - GET, POST, DELETE primarily. This is the level at which REST really comes into picture.

At Level 3, you start using hypermedia controls to make your API truly RESTful.

Suggested links for further reading:

• What is the Richardson Maturity Model?
• Martin Fowler's blog: Richardson Maturity Model

Matted

Answer 8

Absolutely correct. I'd note in addition that that URI templates are perfectly fine within a RESTful application so long as the patterns are from documents received from the server (OpenSearch being a suitable example). For URI templates, you document where they're being used and what the expected placeholders in the template are, but not the templates themselves. Slightly contrary to what Wahnfrieden said, this isn't an exception.

For example, at my work we have a internal domain management system, and the service document specifies two URI templates: one for producing a best guess URI for a domain resource, and another for constructing a URI for querying domain availability. It's still possible to page through the domains collection to figure out what the URI of a given domain is, but given the immense number of domains it manages, this wouldn't be feasible for the client, so giving them a way to guess what the URI of a domain resource might be is a huge win in terms of ease of implementation from the client's perspective, and bandwidth from the server's.

On to your question: Our normative documentation is exposed resources, the effect of various methods on those resources, and the representation media types used and their schemas, and what kind of resources the URIs in those representions point to.

We also include non-normative (informative) documentation that has attached to it a disclaimer not to read too much into the URIs mentioned in the document, which gives examples of typical client-server interactions. This puts the rather abstract normative documentation in concrete terms.

Chalco

It's fine to provide URI templates as part of your API, out-of-band. Just PLEASE do NOT refer to this as REST, because it's not. That's a huge amount of coupling, and exactly what REST was made to avoid. But like you say, REST is not for every application. So don't pretend every application is REST. – Scheel

Actually, I agree. I believe that's what I said. However, I really can't see any good reason for providing URI templates out-of-band. – Chalco

Answer 9

Let's assume GET /foos/createForm is invoked to get form fields values for which must be provided when we go to create POST /foos . Now this particular URL i.e the 1 used to create foos should be mentioned within the response for GET /foos/createForm as a submit action link according to Fielding's proposition, right ?
Then what is the benefit of mapping actions to well-known Http verbs to actions, "convention over code/config" thing is nullified.

Phototube