How to Use HATEOAS in REST API: Simple Guide and Example

To use HATEOAS in a REST API, include hypermedia links in your API responses that guide clients on available actions dynamically. These links are usually added as a _links section in JSON responses, helping clients discover related resources and operations without hardcoding URLs.

Syntax

HATEOAS responses typically include a _links object that holds URLs for related actions or resources. Each link has a rel (relation) name and an href (URL) to guide the client.

Example parts:

• _links: Container for all links.
• self: Link to the current resource.
• rel: Relation type describing the link's purpose.
• href: The URL for the link.

json

{
  "data": { "id": 1, "name": "Item 1" },
  "_links": {
    "self": { "href": "/items/1" },
    "update": { "href": "/items/1/update" },
    "delete": { "href": "/items/1/delete" }
  }
}

Example

This example shows a simple REST API response for an item with HATEOAS links. The _links section tells the client how to get, update, or delete the item.

javascript

const express = require('express');
const app = express();

app.get('/items/:id', (req, res) => {
  const id = req.params.id;
  const item = { id: Number(id), name: `Item ${id}` };

  const response = {
    data: item,
    _links: {
      self: { href: `/items/${id}` },
      update: { href: `/items/${id}/update` },
      delete: { href: `/items/${id}/delete` }
    }
  };

  res.json(response);
});

app.listen(3000, () => console.log('API running on http://localhost:3000'));

Output

API running on http://localhost:3000

// When you visit http://localhost:3000/items/1 you get:
// {
//   "data": { "id": 1, "name": "Item 1" },
//   "_links": {
//     "self": { "href": "/items/1" },
//     "update": { "href": "/items/1/update" },
//     "delete": { "href": "/items/1/delete" }
//   }
// }

Common Pitfalls

Common mistakes when using HATEOAS include:

• Not including _links or missing important actions, which makes the API less discoverable.
• Hardcoding URLs on the client side instead of using links from the response.
• Using inconsistent relation names (rel) that confuse clients.
• Returning links that do not match actual API routes.

Always keep links up to date and meaningful.

json

/* Wrong: No links included */
{
  "data": { "id": 1, "name": "Item 1" }
}

/* Right: Include _links with clear relations */
{
  "data": { "id": 1, "name": "Item 1" },
  "_links": {
    "self": { "href": "/items/1" },
    "update": { "href": "/items/1/update" }
  }
}

Quick Reference

Tips for using HATEOAS in REST APIs:

• Always include a self link to identify the current resource.
• Use meaningful rel names like update, delete, next, or prev.
• Keep URLs relative to support different environments.
• Document your link relations clearly for API users.

Key Takeaways

HATEOAS adds navigational links in REST API responses to guide clients dynamically.

Include a _links object with self and related action URLs in your JSON responses.

Avoid hardcoding URLs on the client; use links provided by the API instead.

Use clear and consistent relation names to describe each link's purpose.

Keep your links accurate and up to date with your API routes.