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