Take the 2-minute tour ×

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:


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 must not define fixed resource names or hierarchies (an obvious coupling of client and server). ...


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.


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:


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

share|improve this question
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. –  Keith Gaughan Jul 22 '09 at 14:48
Keith, "explaining the change in mindset" is something he should do in his blog, not on SO. –  John Saunders Jul 22 '09 at 16:44
He's not explaining his change in mindset, he's asking if his understanding is accurate. –  aehlke Jul 27 '09 at 14:05
Excellent summary. I learned more from this question than from most answers. –  Martin Konecny Jul 27 at 16:47

8 Answers 8

up vote 11 down vote accepted

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.

share|improve this answer

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.

share|improve this answer
What about the Sun Cloud API: kenai.com/projects/suncloudapis/pages/Home –  Rich Apodaca Jul 22 '09 at 18:23
Wow. That Resource Model page brought a tear to my eye. Let's hope this starts a trend. –  Darrel Miller Jul 23 '09 at 0:28
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). –  jkp Nov 21 '09 at 15:06
@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... –  edsioufi Sep 4 '13 at 22:12
Does this one help? api.foxycart.com/docs –  Mladen B. Dec 5 at 14:13

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

share|improve this answer

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.

share|improve this answer

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

share|improve this answer

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

share|improve this answer

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.

share|improve this answer
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. –  aehlke Jul 27 '09 at 14:04
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. –  Keith Gaughan Aug 19 '09 at 10:08

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.

share|improve this answer

Your Answer


