Home » Hypermedia


There is currently no standardized way of implementing hypermedia, and many specs have been developed and are even being created as we speak. However, while it’s important to innovate when building your API, it’s also important to adhere to the tools and standards that developers know, and the specifications that have been carefully tried and tested. While it is worthwhile to try specs such as CPHL, Siren, UBER, Yahapi and others in your own personal projects, it is recommended to utilize HAL or JSONAPI for your production API unless you have a strong reason to choose a different specification.

In a nuttshell: HAL and JSONAPI are the most popular. JSON-LD is a W3C standard but was really designed for linking definitions between databases. Collection+JSON was one of the original ones created by Mike Amundsen. Great specification, but less used than HAL or JSON API. Siren is actually really interesting in that it went a different direction. Siren has foreign properties, class properties, and entity properties, and it’s action‑driven like CPHL. Action-driven means that a resource may be included multiple times if necessary (ie edit, delete), but described by its title, description, and the methods it utilizes – making it more explicit than other formats.

A recent draft initiative is HAL-FORMS: it extends HAL with the possibility of capturing ‘templates’ to specify operations over a resource and the inputs of the operations (‘template’ property).

Unfortunately, no hypermedia specification is perfect!

Format Specifications
HAL https://tools.ietf.org/html/draft-kelly-json-hal-08
JSON-LD https://www.w3.org/TR/json-ld/
JSONAPI https://jsonapi.org/
Collection+JSON http://amundsen.com/media-types/collection/
Siren https://github.com/kevinswiber/siren/blob/master/README.md
CPHL https://github.com/mikestowe/CPHL
HAL-FORMS https://rwcbook.github.io/hal-forms/
All formats Explanation of all formats
Kevin Sookocheff I https://sookocheff.com/post/api/on-choosing-a-hypermedia-format/
Kevin Sookocheff II https://gist.github.com/soofaloofa-zz/9350847
Michael Stowe https://restapilinks.com/wp-content/uploads/2021/01/0.pdf (p.124)
Java Code Geeks https://www.javacodegeeks.com/restful-services-with-hateoas-hypermedia-the-secret-ingredient-of-rest.html
Nordic APIs https://nordicapis.com/designing-evolvable-apis-for-the-web-formats/
Single format Explanation of a single format
JSONAPI https://nordicapis.com/the-benefits-of-using-json-api/
JSON-LD https://nordicapis.com/what-is-json-ld/
CPHL https://www.nginx.com/blog/building-your-api-for-longevity-best-practices/
HAL – Amazon API Gateway https://docs.aws.amazon.com/apigateway/api-reference/
INNOQ – Pragmatic HAL APIs https://www.innoq.com/de/articles/2020/12/rest-apis-with-hal/ (HAL extensions to disclose HTTP methods)
Comparison Formats compared
Antoine Cheron https://www.fabernovel.com/en/article/tech-en/which-technologies-should-you-use-to-build-hypermedia-apis
Misc Various useful links
Converting HAL -> JSON-LD https://ontola.io/blog/json-hal-ld/
Hypermedia Maturity Model https://8thlight.com/blog/jason-desrosiers/2018/05/30/the-hypermedia-maturity-model.html
Kai Tödter’s HAL Explorer https://github.com/toedter/hal-explorer (An API explorer for RESTful Hypermedia APIs using HAL or HAL-FORMS)