HATEOAS concept overview in Express

Introduction

HATEOAS helps your app tell clients what they can do next by giving links in responses. It makes APIs easier to use and explore without extra instructions.

When building APIs that guide clients through available actions automatically.

When you want your API to be self-explanatory and reduce client-side hardcoding.

When you want to improve API discoverability for new developers or tools.

When your API has many related resources and actions that depend on context.

When you want to follow REST principles for better web service design.

Syntax

Express

res.json({
  data: {...},
  links: [
    { rel: 'self', href: '/resource/1' },
    { rel: 'update', href: '/resource/1' },
    { rel: 'delete', href: '/resource/1' }
  ]
});

The response includes a links array with objects describing possible next actions.

Each link has a rel (relation) describing the action and an href URL to perform it.

Examples

Response shows the book data and links to itself and its author.

Express

res.json({
  data: { id: 1, name: 'Book' },
  links: [
    { rel: 'self', href: '/books/1' },
    { rel: 'author', href: '/authors/5' }
  ]
});

Response includes actions to approve or cancel an order.

Express

res.json({
  data: { id: 2, status: 'pending' },
  links: [
    { rel: 'approve', href: '/orders/2/approve' },
    { rel: 'cancel', href: '/orders/2/cancel' }
  ]
});

Sample Program

This Express server sends book data with HATEOAS links showing what actions the client can take next.

Express

import express from 'express';
const app = express();

app.get('/books/:id', (req, res) => {
  const bookId = req.params.id;
  // Simulated book data
  const book = { id: bookId, title: 'Learn Express' };

  res.json({
    data: book,
    links: [
      { rel: 'self', href: `/books/${bookId}` },
      { rel: 'update', href: `/books/${bookId}` },
      { rel: 'delete', href: `/books/${bookId}` }
    ]
  });
});

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

Important Notes

HATEOAS responses help clients navigate your API without guessing URLs.

Keep links relevant to the current resource and user permissions.

Use clear rel names so clients understand the actions easily.

Summary

HATEOAS adds links in API responses to guide clients on next steps.

It makes APIs easier to use and discover without extra documentation.

Express apps can send HATEOAS links as part of JSON responses.