Hypermedia and REST

There are four different Levels in the REST API Evolution. They are described in the Richardson Maturity Model. You can find more information in this article from Martin Fowler.

Hypermedia represents the links to your API. The main characteristics of Hypermedia are:

• Decouple the Server and the Client
• Links are to help developers know how to use the API
  • The developer interacts with the first URL
  • The Navigation is controlled by the server
• API becomes self-describing
• Links become the application state
• HATEOAS

(HATEOAS) Hypermedia as the Engine of Application State. The principle of addressability just says that every resource should have its own URL. If something is important to your application, it should have a unique name, a URL, so that you and your users can refer to it unambiguously.

The URI Templates for HATEOAS are covered in RFC 6570 and the Link Header in RFC 5988.

At its core, HATEAOAS provides a way to interact with the REST API entirely through hyperlinks. With each call that you make to the API, we’ll return an array of links that allow you to request more information about a call and to further interact with the API. You no longer need to hard code the logic necessary to use the REST API.

HATEOAS links are contextual, so you only get the information that is relative to a specific request.

Details about Hypermedia formats are described in Hypermedia Formats.

On Choosing a Hypermedia Format provides a good overview and guide of Hypermedia Formats.

Relative vs Absolute

It is strongly recommended that the URLs generated by the API should be absolute URLs.

The reason is mostly for ease of use by the client, so that it never has to find out the correct base URI for a resource, which is needed to interpret a relative URL. The URL RFC specifies the algorithm for determining a base URL, which is rather complex. One of the options for finding the base URL is to use the URL of the resource that was requested. Since a resource may appear under multiple URLs (for example, as part of a collection, or stand-alone), it would be a significant overhead to a client to remember where he retrieved a representation from. By using absolute URLs, this problem doesn’t present itself.

On determining which URI to return

In Hypermedia responses, we require the use of absolute URLs (as stated in the above section). If your API lives behind an API Management, the actual URI of the (backend) API will be different from the URI which is the one to call, i.e. the one of the API management gateway.

As a rule, the API Management gateway MUST pass an additional header with the call to the backend API containing the API Gateway base URL for the API at hand. This header must be named Forwarded, as described in RFC 7239. The two parameters host and proto are pre-defined in the RFC, whereas we need additional ones, which is explicitly allowed per Section 5.5 of the RFC:

• host: Must contain the host name of the API Gateway; this is the host an API client uses to actually talk to the API.
• proto: The protocol/schema to use. This MUST be https for all of our APIs (see security and authentication)
• Extension port: OPTIONAL - The port of the API Gateway. Usually this can be assumed to be 443 if proto equals https; use if deviating
• Extension prefix: The base path of the API on the API Gateway, e.g. /someapi/v1.

Example: A request goes to https://api.contenthub.haufe.io/ingest/v1/bulk/63874638746834, which is forwarded to the ingest service in the backend. The API Gateway must pass on this information in the following way:

Forwarded: proto=https;host=api.contenthub.haufe.io;port=443;prefix=/ingest/v1

If present, this header MUST be used to assemble hypermedia links in responses, so that an API consumer is directed to the right place.

If this header is not present, the API backend SHOULD use its own absolute base URI as a fallback.