HATEOAS

HATEOAS is the constraint that a client should discover what it can do from the responses it receives, rather than from URLs hard-coded against documentation. Each representation carries links, and those links are what drives the client from one state to the next.

How it works

A response includes a links structure — commonly `_links` — naming the available transitions and their URLs: self, next, cancel, approve. A client follows the link named for what it wants to do. Because the available links depend on the current state, an order that has shipped simply does not carry a cancel link, and the client needs no rule of its own about when cancelling is allowed.

The misconception

That HATEOAS is academic and nobody ships it. Partial HATEOAS is everywhere: the `next` URL in a paginated response is exactly this idea, and a client that follows it rather than incrementing a page counter is already benefiting — it keeps working when the server moves to cursor pagination.

Try it here

The Protocol Lab document endpoints attach `_links` to every item. The Bank transaction list uses a cursor the client is meant to follow rather than construct.

Related

• Testing pagination against a real API
• What a REST API is

Other terms

• Mock API — A stand-in for a real API that returns realistic responses without the real system behind it.
• REST API — An API that models a system as addressable resources, manipulated with standard HTTP methods.
• ETag — An opaque version identifier for a representation, used to avoid re-sending it and to detect conflicting writes.
• Bearer token — A credential where possession alone grants access — whoever holds it can use it.
• JWT (JSON Web Token) — A signed, self-contained token whose payload the server can verify without a database lookup.
• Webhook — An HTTP callback the server sends you when something happens, instead of you polling to ask.

All glossary terms · Testing techniques · All 39 mock REST APIs