Skip to main content

HATEOAS in 2026: Is Hypermedia API Design Dead?

·APIScout Team
hateoashypermediarest apiapi designapi architecture

HATEOAS in 2026: Is Hypermedia API Design Dead?

HATEOAS (Hypermedia as the Engine of Application State) is the most debated REST constraint. In theory, API responses include links that tell clients what actions are possible next. In practice, almost nobody implements it. Let's be honest about why.

What HATEOAS Actually Means

A HATEOAS-compliant response includes links to related resources and available actions:

{
  "data": {
    "id": "order_123",
    "status": "pending",
    "total": 4999
  },
  "links": {
    "self": "/api/orders/order_123",
    "cancel": "/api/orders/order_123/cancel",
    "payment": "/api/orders/order_123/pay",
    "customer": "/api/customers/cust_456"
  }
}

The client doesn't need to hardcode URLs. It discovers available actions from the response. If the order is already paid, the payment link disappears. If it can't be cancelled, the cancel link disappears.

Why Most APIs Ignore HATEOAS

1. Clients Hardcode Anyway

In practice, frontend developers build components that call specific endpoints. They don't write generic link-following code. The UI needs to know what /api/orders/order_123/cancel does regardless of whether it discovers the URL from a link or constructs it.

2. Type Safety > Discoverability

TypeScript, code generation from OpenAPI specs, and type-safe API clients (tRPC, orval, openapi-typescript) provide compile-time safety. Hardcoded, typed API calls are safer than dynamic link-following.

3. Bandwidth Overhead

Links add bytes to every response. In a mobile app making hundreds of API calls, including navigation links the client never uses wastes bandwidth.

4. Complexity Without Clear ROI

Implementing HATEOAS requires building a link generation system, maintaining link relationships, and handling link-driven state machines. Most teams can't justify this overhead for APIs consumed by their own frontends.

When HATEOAS Actually Helps

1. Long-Lived API Clients

If API clients are deployed and can't be easily updated (IoT devices, native mobile apps with slow update cycles), HATEOAS allows the server to change URL structures without breaking clients.

2. Complex State Machines

When resources have complex state transitions (order → paid → shipped → delivered → returned), links communicate which transitions are available. This prevents clients from showing a "Cancel" button on an already-shipped order.

3. API Marketplaces and Aggregators

Generic API clients (like Postman, API explorers) benefit from discoverability. HATEOAS lets these tools navigate an API without prior knowledge.

4. Multi-Service Architectures

When an API aggregates multiple services, links can point to different service URLs. The client follows links without knowing which service handles what.

Practical Alternatives

1. OpenAPI Specification

Document your API with OpenAPI/Swagger. Clients generate typed code from the spec. Changes are communicated through spec updates, not runtime links.

The most common "HATEOAS-lite" pattern — include next and previous links in paginated responses:

{
  "data": [...],
  "links": {
    "next": "/api/users?cursor=abc123",
    "prev": "/api/users?cursor=xyz789"
  }
}

This is genuinely useful without full HATEOAS.

3. Actions Array

Instead of links to URLs, include an array of available actions:

{
  "data": { "id": "order_123", "status": "pending" },
  "available_actions": ["cancel", "pay", "update"]
}

The client knows which buttons to show without constructing URLs from links.

4. GraphQL Introspection

GraphQL's schema introspection serves the same discoverability purpose as HATEOAS — clients can explore available types, fields, and operations at runtime.

The Verdict

HATEOAS isn't dead — it's niche. For most API teams building products consumed by their own frontends, it adds complexity without proportional benefit. OpenAPI specs, typed clients, and good documentation solve the same problems more practically.

Use HATEOAS when:

  • Clients can't be updated alongside the API
  • Complex state machines need runtime action discovery
  • Building a truly generic API browser/explorer

Skip HATEOAS when:

  • You control both client and server
  • You have typed API clients (TypeScript + code gen)
  • You're building a standard CRUD API

Designing APIs? Explore API design patterns and best practices on APIScout — architecture guides, comparisons, and developer resources.

Comments