I am learning a bit about REST and am intrigued by the concept of a uniform interface, and the ability of a client to follow hypermedia links in order to detect service capabilities.

As I understand it, the RESTful server will return a hypermedia document "representation" of an "entity" that contains relevant links. If using the HTML media type, for example, the links will be decorated with a "rel" attribute that specifies the meaning of the link-- the client should not look at the link's href, which is an opaque resource identifier. The client then follows the opaque link to another resource which returns a new representation that is related to the current one in a manner described by the rel attribute.

What I don't understand is how the client knows what rel values to look for. Seems that these still need to be agreed between the client and server. How is this agreement communicated? Is there a RESTful equivalent of, say, a WSDL?

  • If you want to document your REST API, you can do it (RAML Swagger etc...). But a true hypermedia would fulfill this objective by allowing to self-describe response (take a look at Hydra) Nov 5, 2015 at 17:40

2 Answers 2


One of the requirements that should be satisfied before you can call an API 'RESTful' is that it should be possible to write a generic client application, on top of that API. With the generic client, a user should be able to access all the API's functionality. A generic client is a client application that does not assume that any resource has a specific structure beyond the structure that is defined by the media type.

In your example, the client application would offer the user the ability to follow the links. The rel attributes are displayed to the user and the client application expects the user to understand these values.

The above is known as the REST requirement to have "Hypermedia as the engine of application state" (HATEOAS). The benefit is, that the client won't break when the back end changes its rel values. Without HATEOAS, the interface is not RESTful.

Now, suppose we have a HTTP/JSON API for a web shop and we want to build a HTML/CSS/JavaScript client that gives our customers an excellent user experience. Would it be a realistic option to let that client be a generic client application? No. We want to provide a specific look-and-feel for every specific data element and every specific application state. We don't want to include all knowledge about these presentation-specifics in the API, on the contrary, the client should define the look and feel and the API should only carry the data. This implies that the client has hard-coded coupling of specific resource elements to specific layouts and user interactions.

Is this the end of HATEOAS and thus the end of REST? Yes and no.

Yes, because if we hard-code knowledge about the API into the client, we lose the benefit of HATEOAS: server-side changes may break the client.

No, for two reasons:

  1. Being "RESTful" is a property of the API, not of the client. As long as it is possible, in theory, to build a generic client that offers all capabilities of the API, the API can be called RESTful. The fact that clients don't obey the rules is not the API's fault. The fact that a generic client would have a lousy user experience is not an issue. Why is it important to know that it is possible to have a generic client, if we don't actually have that generic client? This brings me to the second reason:
  2. A RESTful API offers clients the option to choose how generic they want to be, i.e. how resilient to server-side changes they want to be. Clients which need to provide a great user experience may still be resilient to URI changes, to changes in default values and more. Clients doing batch jobs without user interaction may be resilient to other kinds of changes.

If you are interested in practical examples, check out my JAREST paper. The last section is about HATEOAS. You will see that with JAREST, even highly interactive and visually attractive clients can be quite resilient to server-side changes, though not 100%.

  • Good answer. Regarding server-side changes (I suppose you mean for instance changes in rel attribute values), I'm not sure how they cancel the benefit of HATEOAS. They should only happen when functional changes are made, in which case it is normal that the client is affected since it can't possibly guess about new requirements being introduced. In such cases, versioning is the solution. Dec 7, 2015 at 13:28

Even with hypermedia REST APIs, the client can not be expected that they can consume just any API without further context.

Clients can only consume documents in a format that is explicitly supported by that client, because otherwise the client has no idea what to do with fields like foo, bar or foobar.
The meaning, syntax and semantics of those fields are described in the specification of the format of the document and that specification should also contain what values are possible for a rel attribute and what those values mean.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.