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.

What is a link relation type?

A link relation type is a token that names the meaning of a link between two resources, such as self, next or edit. IANA maintains a registry of standard relation names; applications may also use extension relations identified by a full URI.

What does the self relation mean?

self points to a URI that is the canonical identifier for the current resource. Clients use it to re-fetch or reference the resource. It appears in HAL _links, JSON:API links and Link headers alike.

How are these used in a Link header?

RFC 8288 defines the Link header where each link carries a rel parameter: Link: ; rel="next". Multiple links are comma-separated. The same relation names work in HAL's _links object and JSON:API's links member.

Does this tool require an internet connection?

No. The relation list and search are fully offline in your browser. Nothing is sent anywhere.

What is the HATEOAS Link Relations Reference?

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. It runs free in your browser on Gera Tools, with nothing uploaded.

HATEOAS Link Relations Reference

Name: HATEOAS Link Relations Reference
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

HATEOAS link relation types

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.

The most important registered relation types

Navigation and pagination

Relation	Meaning
`self`	The canonical URI for the current resource; always include this
`next`	The immediately following resource in a series
`prev`	The immediately preceding resource
`first`	The first resource in the series
`last`	The last resource in the series

A paged collection should include self, next, prev, first, and last on every page so a client can navigate without knowing the URL structure.

Editing and actions

Relation	Meaning
`edit`	A URI that accepts PUT or PATCH to modify the resource
`delete`	A URI to DELETE the resource (extension relation, not IANA-registered)
`create-form`	A form definition for creating a new resource
`edit-form`	A form definition for editing the resource

Describing and linking

Relation	Meaning
`collection`	The collection resource that contains this item
`item`	An item that is part of this collection
`describedby`	A URI returning documentation or a schema for the resource
`profile`	A profile URI listing semantics or constraints
`alternate`	An alternative representation, for example a different format

Practical example: a paginated article API

{
  "_links": {
    "self":  { "href": "/articles?page=3" },
    "prev":  { "href": "/articles?page=2" },
    "next":  { "href": "/articles?page=4" },
    "first": { "href": "/articles?page=1" },
    "last":  { "href": "/articles?page=12" },
    "collection": { "href": "/articles" }
  },
  "_embedded": { "items": [ ... ] }
}

A generic client that understands these relations can paginate, navigate to the collection, and show an “edit” button without any hardcoded knowledge of the URL structure.

Extension relations and custom rels

When no IANA-registered name covers your link’s meaning, use a full absolute URI as the relation type — for example https://api.example.com/rels/approve. This avoids collisions with future IANA registrations and makes the semantic unambiguous. Never invent bare words like rel="approve" as that namespace is implicitly reserved for future registration.

Tips and common mistakes

Include self on every single resource — not just collections. It lets clients cache, share, and re-fetch the resource reliably.
Pagination is a four-link contract: if you only emit next and prev, clients cannot jump to the first or last page without iterating.
edit points to the editable URI (often the same as self), not to a form renderer — do not confuse it with edit-form.
Extension relations should be full URIs, not bare custom words.