Gera Tools

HATEOAS Link Relations Reference

REST HATEOAS link relation names — self, next, edit, describedby — with semantics.

Reference for RESTful HATEOAS link relation types — self, next, prev, edit, collection, describedby and more — with IANA registration status and HAL / JSON:API usage notes.

What is HATEOAS?

HATEOAS (Hypermedia As The Engine Of Application State) is a REST constraint where responses include hyperlinks that tell the client what it can do next. Instead of hard-coding URLs, the client follows links by their relation name, so the server can change URLs freely.

In a hypermedia REST API, responses carry links named by relation type so the client follows actions by meaning rather than by hard-coded URL. This reference lists the common IANA-registered relation names with their semantics and notes on use in Link headers, HAL and JSON:API.

How it works

A link relation pairs a target URI with a rel token that names the link’s meaning. The same tokens appear in three common carriers:

Link: </articles/1>; rel="self", </articles?page=2>; rel="next"
{ "_links": { "self": { "href": "/articles/1" },
              "next": { "href": "/articles?page=2" } } }

Registered relations (per IANA, originally RFC 8288 / RFC 5988) have agreed meanings — self, next, prev, first, last, edit, collection, describedby — while custom relations use a full URI to avoid collisions.

Tips and notes

  • Use self on every resource so clients always have a canonical URI.
  • Pagination uses first / prev / next / last together.
  • edit points to a URI that can be used to edit the resource (e.g. via PUT).
  • Extension relations should be full URIs, not bare custom words.