Introduction to hypermedia based API’s

In a previous blog post I wrote about pragmatic REST — while this is a good style for CRUD based applications it also have some drawbacks. One of the drawback is the coupling between client and server. The client needs to know which endpoints the server exposes. It also need to understand when to call which endpoint.

This coupling becomes a problem when you multiply the number of clients and some of which you may not have control of.

Why Hypermedia

Hypermedia can help you achieve less coupling between client and server — said in another way hypermedia can help with the when and where. When should you call the endpoint and where it can be found.

Typically a hypermedia API will expose a single endpoint that the client connect to — and that is the only endpoint the client knows about. Based on what endpoint the client calls — the server will respond with different links to guide what can be done.

Example response with the media-type application/hal+json

When you read about hypermedia you will come across the acronym HATEOAS. This means hypermedia as the engine of application state. The server will guide the clients by embedding links into the responses — the server uses hypermedia for state transitions on the clients.

Deciding on the media-type

One of the first and most important decisions is to decide on the media-type(s) that your API will support. The media-type is the contract with the client. You can define your own or use some of the predefined used in the industry.

An example of a media-type is application/hal+json which is very easy to use and can most likely be used with your current responses.

If you choose an already existing media-type you can benefit from the ecosystem. For instance — for application/hal+json there is a chrome plugin to allow the consumer to explore the API. This way you can build your documentation for the API dynamically.

Designing your own media-type involves more work and for media-types you will often see people refer to the H-factors of a media-type.

The H Factor of a media-type is a measurement of the level of hypermedia support and sophistication of a media-type.

Every API is different — and the amount of H-factors you will want to support will vary with each use case.

Link relation types

All the links in the response from the server has an rel attribute that tells the consumer the semantics of the link. There have been done some work by IANA on defining names for typical rel names.

This is where the coupling between client and server is still not as loosely coupled as you might wish. The consumer would have to know what each links means — in the future you can hope that API designer will align on these names — convention over configuration.


Hypermedia based API can help you further decouple client and server — however it is not a silver bullet.

For some use cases — crud based API is still valid. If you however have more needs this can be a viable option.

Hope this helps!

Like what you read? Give Jacob Lorenzen a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.