You've probably built dozens of APIs that you called "RESTful". You used HTTP methods correctly, structured your URLs properly, and returned JSON responses.

But here's the truth: if your API doesn't include hypermedia links, it's not truly RESTful.

HATEOAS (Hypermedia as the Engine of Application State) is the most misunderstood and frequently skipped constraint of REST. Without it, your frontend clients become tightly coupled to your API structure, hardcoding URLs and duplicating business logic to determine which actions are available.

Today, we will learn why most APIs ignore HATEOAS, how it actually works in practice, and when you should invest the effort to implement it properly.

In this post, we will explore:

• What is REST and What Are The REST Constraints
• Richardson Maturity Model
• Why 90% of APIs Are Not RESTful
• HATEOAS in Practice in ASP .NET Core
• Frontend Application Using HATEOAS
• When HATEOAS Pays Off — And When It Doesn't

Let's dive in.

REST (Representational State Transfer) is not a protocol or a standard. It's an architectural style that Roy Fielding introduced in his doctoral dissertation.

REST was designed to leverage the architecture that made the web successful.

The web works because it's decoupled, scalable, and clients (browsers) don't need to know the entire structure of every website upfront. They follow links. REST applies this same principle to APIs.

When you build a RESTful API, you're not just creating endpoints that return data. You're building a system where the server guides the client through available actions, just like a website guides you through clickable links.

For an API to be truly RESTful, it must follow six architectural constraints:

1. Client-Server Architecture

The client and server are separated. The client handles the user interface and user state, while the server manages data storage and business logic. This separation allows each side to evolve independently. You can update your backend implementation without breaking clients, as long as you maintain the contract.

2. Stateless

Each request from the client must contain all information needed to understand and process that request. The server doesn't store client context between requests. Statelessness makes your API more scalable because any server instance can handle any request without needing to know what happened before.

3. Cacheable

Responses must explicitly indicate whether they can be cached or not. You use HTTP headers like Cache-Control, ETag, and Last-Modified to tell clients and intermediaries (like CDNs) what they can cache and for how long.

4. Uniform Interface

This is the fundamental constraint that makes REST different from other architectural styles.

It has four sub-constraints:

• Resource Identification: Resources are identified by URIs. A resource is any concept that can be named - a user, an order, a product.
• Resource Manipulation Through Representations: When you receive a resource representation (like JSON), it contains enough information to modify or delete that resource.
• Self-Descriptive Messages: Each message includes enough information to describe how to process it. HTTP methods (GET, POST, PUT, DELETE) tell you the operation. Content-Type headers tell you the format.
• Hypermedia as the Engine of Application State (HATEOAS): Responses should include links to related actions and resources, guiding clients on what they can do next.

5. Layered System

A client shouldn't be able to tell whether it's connected directly to the end server or to an intermediary. You can add load balancers, caches, or API gateways without the client knowing about it. This constraint enables scalability by allowing you to distribute services across multiple servers.

6. Code on Demand (Optional)

The only optional constraint. Servers can extend client functionality by transferring executable code, like JavaScript. Most APIs don't use this constraint, and that's perfectly fine.

In practice, we needed a way to measure how close an API gets to being truly RESTful.

Leonard Richardson created a maturity model that breaks down REST adoption into four levels.

Level 0: The Swamp of POX (Plain Old XML)

At this level, you're using HTTP as a transport mechanism, nothing more. You have a single URI endpoint that typically uses only POST requests, and the request body contains all the information about what operation to perform. This is essentially RPC (Remote Procedure Call) over HTTP. SOAP APIs often operate at this level.

Endpoint example: /api/service

Level 1: Resources

At this level, you start breaking down your single endpoint into multiple resource-based URIs. Instead of one endpoint handling everything, you have different URIs for different resources.

Endpoint examples: /api/orders, /api/customers, /api/products

Level 2: HTTP Verbs

Now you're using HTTP methods correctly. GET for retrieving data, POST for creating, PUT for updating, and DELETE for removing. You also use HTTP status codes meaningfully.

Endpoint examples:

• GET /api/orders/123 - retrieve an order
• POST /api/orders - create a new order
• PUT /api/orders/123 - update an order
• DELETE /api/orders/123 - delete an order

Proper status codes: 200 OK, 201 Created, 404 Not Found, etc.

Most APIs that call themselves RESTful are at this level. You're using resources, HTTP methods, and status codes correctly. Your API is predictable and follows web standards. But you're still missing the last piece.

Level 3: Hypermedia Controls (HATEOAS)

This is true REST. Your API responses include links to related resources and available actions. The client doesn't need to know your URL structure upfront. The server tells the client what it can do next.

Most APIs stop at Level 2, and it works.

Such APIs are predictable; they follow HTTP standards, and developers know how to build them.

Reaching Level 3 requires:

• More implementation effort
• Larger response payloads
• Client code that knows how to parse and follow links
• A shift in thinking about how APIs should work

Let's explore why so many APIs skip HATEOAS and what problems this creates.

1. It's More Work

Implementing HATEOAS means generating links for every response.

A simple GET /orders/123 response goes from this:

json
1{
2  "id": "123",
3  "status": "Pending",
4  "total": 99.99
5}

To this:

json
1{
2  "id": "123",
3  "status": "Pending",
4  "total": 99.99,
5  "links": [
6    { "rel": "self", "href": "/orders/123", "method": "GET" },
7    { "rel": "pay", "href": "/orders/123/payment", "method": "POST" },
8    { "rel": "cancel", "href": "/orders/123", "method": "DELETE" }
9  ]
10}

That's extra code to write, maintain, and test.

2. Larger Payloads

Every response becomes bigger because you're including link objects. When you return a list of 100 orders, you're now including links for each one. Your response size grows significantly. For mobile applications on slow networks, this matters. For high-traffic APIs, the bandwidth costs add up.

3. No Standard Format

Unlike HTTP methods or status codes, there's no single standard for hypermedia. This lack of standardization means every team invents their own approach, making it harder for client developers to learn and adopt.

4. Client Complexity

Your frontend now needs to parse links and use them instead of hardcoded URLs.

5. Feels Like Over-Engineering

When you're shipping features, HATEOAS feels like over-engineering. Why add complexity when hardcoded URLs work fine? The benefits of HATEOAS appear later, during maintenance and evolution. But deadlines are now.

6. Internal APIs Don't Need It

If you control both the frontend and backend, deploying them together, why bother with hypermedia? You can update both sides simultaneously.

Skipping HATEOAS seems practical until you hit these issues:

1. Tight Coupling

Your frontend hardcodes URLs like /orders/123/payment. When you refactor and move the payment to /payments?orderId=123, it causes every client to break.

2. Duplicated Business Logic

Your backend knows an order can only be cancelled if it's not yet shipped. But your frontend also implements this check to hide the Cancel button appropriately.

Now you have the same business rule in two places. When rules change, you update both. When you forget, users see buttons that trigger 403 Forbidden errors.

3. Poor Discoverability

New developers joining your project need comprehensive documentation to understand what actions are possible on each resource in each state. With HATEOAS, they can explore by following links. The API tells them what's possible.

Enough theory, let's see how HATEOAS works in practice.

We'll build an Orders API in ASP.NET Core that implements HATEOAS.

First, we need a way to represent hypermedia links. Here's our LinkResponse model:

csharp
1public record LinkResponse
2{
3    public required string Href { get; init; }
4    public required string Rel { get; init; }
5    public required string Method { get; init; }
6}

Each link tells the client:

• Href: Where to send the request
• Rel: What this link represents (relationship type like "self", "update", "delete")
• Method: Which HTTP method to use

Next, we need a way to generate links. Here's the LinkService:

csharp
1public sealed class LinkService(
2    LinkGenerator linkGenerator,
3    IHttpContextAccessor httpContextAccessor)
4{
5    public LinkResponse Create(
6        string endpointName,
7        string rel,
8        string method,
9        object? values = null,
10        string? controller = null)
11    {
12        var href = linkGenerator.GetUriByAction(
13            httpContextAccessor.HttpContext!, 
14            endpointName, 
15            controller, 
16            values);
17
18        return new LinkResponse
19        {
20            Href = href ?? throw new InvalidOperationException("Invalid endpoint name provided"),
21            Rel = rel,
22            Method = method
23        };
24    }
25}

This service uses ASP.NET Core's LinkGenerator to create URLs based on action names. When you rename routes, the links update automatically.

Our response models need to carry links. Here's OrderResponse:

csharp
1public record OrderResponse
2{
3    public required Guid Id { get; init; }
4    public required string OrderNumber { get; init; }
5    public Guid? CustomerId { get; init; }
6    public required DateTime OrderDate { get; init; }
7    public required decimal TotalAmount { get; init; }
8    public required OrderStatus Status { get; init; }
9    public DateTime? ShippedDate { get; init; }
10    public string? ShippingAddress { get; init; }
11    public required List<OrderItemResponse> Items { get; init; }
12    public List<LinkResponse> Links { get; set; } = [];
13}

The Links property holds all available actions for this order. It starts empty, and we populate it based on the order's current state.

Now comes the interesting part. Let's look at the OrdersController and see how it includes links:

csharp
1[HttpGet(OrdersRouteConsts.GetOrderById)]
2public async Task<IActionResult> GetOrderById(
3    Guid id,
4    GetOrderByIdHandler handler,
5    LinkService linkService,
6    CancellationToken cancellationToken)
7{
8    var response = await handler.HandleAsync(id, cancellationToken);
9
10    if (response is null)
11    {
12        return NotFound();
13    }
14
15    response.Links =
16    [
17        linkService.Create(nameof(GetOrderById), "self", HttpMethods.Get, new { id }),
18        linkService.Create(nameof(CreateOrder), "create", HttpMethods.Post),
19        linkService.Create(nameof(UpdateOrder), "update", HttpMethods.Put, new { id }),
20        linkService.Create(nameof(DeleteOrder), "delete", HttpMethods.Delete, new { id }),
21        linkService.Create(nameof(OrderItemsController.AddItemToOrder), "add-item", HttpMethods.Post,
22            new { orderId = id }, nameof(OrderItemsController).Replace("Controller", ""))
23    ];
24
25    return Ok(response);
26}

Every time we return an order, we include links to:

• self: Get this order again
• create: Create a new order
• update: Update this order
• delete: Delete this order
• add-item: Add an item to this order

We reference action names like nameof(UpdateOrder). If we refactor our route structure, the links stay correct.

Here's how we handle order items:

csharp
1[HttpGet(OrderItemsRouteConsts.GetOrderItemById)]
2public async Task<IActionResult> GetOrderItemById(
3    Guid orderId,
4    Guid itemId,
5    GetOrderItemByIdHandler handler,
6    LinkService linkService,
7    CancellationToken cancellationToken)
8{
9    var response = await handler.HandleAsync(orderId, itemId, cancellationToken);
10
11    if (response is null)
12    {
13        return NotFound();
14    }
15
16    response.Links =
17    [
18        linkService.Create(nameof(GetOrderItemById), "self", HttpMethods.Get,
19            new { orderId, itemId }),
20            
21        linkService.Create(nameof(UpdateOrderItem), "update", HttpMethods.Put,
22            new { orderId, itemId }),
23            
24        linkService.Create(nameof(DeleteOrderItem), "delete", HttpMethods.Delete,
25            new { orderId, itemId })
26    ];
27
28    return Ok(response);
29}

Each order item gets links to view, update, or delete itself.

When a client calls GET /orders/123, they receive JSON like this:

json
1{
2  "id": "7c533935-ee09-4435-9c00-2a68df13fbca",
3  "orderNumber": "ORD-2025-001-UPDATED",
4  "customerId": "f09f4e75-8a6d-4640-9893-c96050883b2b",
5  "orderDate": "2025-10-14T17:41:11.868504Z",
6  "totalAmount": 349.97,
7  "status": 1,
8  "shippedDate": "2025-01-15T10:30:00Z",
9  "shippingAddress": "456 Oak Ave, Los Angeles, CA 90001",
10  "items": [],
11  "links": [
12    {
13      "href": "https://localhost:7023/orders/7c533935-ee09-4435-9c00-2a68df13fbca",
14      "rel": "self",
15      "method": "GET"
16    },
17    {
18      "href": "https://localhost:7023/orders",
19      "rel": "create",
20      "method": "POST"
21    },
22    {
23      "href": "https://localhost:7023/orders/7c533935-ee09-4435-9c00-2a68df13fbca",
24      "rel": "update",
25      "method": "PUT"
26    },
27    {
28      "href": "https://localhost:7023/orders/7c533935-ee09-4435-9c00-2a68df13fbca",
29      "rel": "delete",
30      "method": "DELETE"
31    },
32    {
33      "href": "https://localhost:7023/orders/7c533935-ee09-4435-9c00-2a68df13fbca/items",
34      "rel": "add-item",
35      "method": "POST"
36    }
37  ]
38}

The client doesn't need to know your URL structure. Everything they need is in the response.

When you return multiple orders, you include links for each one:

csharp
1[HttpGet(OrdersRouteConsts.GetOrdersByCustomerId)]
2public async Task<IActionResult> GetOrdersByCustomerId(
3    Guid customerId,
4    GetOrdersByCustomerIdHandler handler,
5    LinkService linkService,
6    CancellationToken cancellationToken)
7{
8    var response = await handler.HandleAsync(customerId, cancellationToken);
9
10    foreach (var order in response)
11    {
12        order.Links =
13        [
14            linkService.Create(nameof(GetOrderById), "self", HttpMethods.Get, new { id = order.Id }),
15            linkService.Create(nameof(CreateOrder), "create", HttpMethods.Post),
16            linkService.Create(nameof(UpdateOrder), "update", HttpMethods.Put, new { id = order.Id }),
17            linkService.Create(nameof(DeleteOrder), "delete", HttpMethods.Delete, new { id = order.Id }),
18            linkService.Create(nameof(OrderItemsController.AddItemToOrder), "add-item", HttpMethods.Post,
19                new { orderId = order.Id }, nameof(OrderItemsController).Replace("Controller", ""))
20        ];
21    }
22
23    return Ok(response);
24}

Each order in the collection gets its own set of contextual links.

Right now, we're including all possible actions regardless of order state.

But here's where HATEOAS becomes useful: you conditionally include links based on the resource's current state.

This is how you can enhance the GetOrderById method to take order state into account:

csharp
1response.Links = [
2    linkService.Create(nameof(GetOrderById), "self", HttpMethods.Get, new { id })
3];
4
5// Only allow updates if the order is Pending
6if (response.Status == OrderStatus.Pending)
7{
8    response.Links.Add(linkService.Create(nameof(UpdateOrder), "update", HttpMethods.Put, new { id }));
9    response.Links.Add(linkService.Create(nameof(DeleteOrder), "cancel", HttpMethods.Delete, new { id }));
10}
11
12// Only allow shipping if the order is Paid
13if (response.Status == OrderStatus.Paid)
14{
15    response.Links.Add(linkService.Create(nameof(ShipOrder), "ship", HttpMethods.Post, new { id }));
16}
17
18// Always allow adding items unless shipped or cancelled
19if (response.Status != OrderStatus.Shipped && response.Status != OrderStatus.Cancelled)
20{
21    response.Links.Add(linkService.Create(nameof(OrderItemsController.AddItemToOrder), "add-item", 
22        HttpMethods.Post, new { orderId = id }, nameof(OrderItemsController).Replace("Controller", "")));
23}

Now your API acts as the engine of the application state. The backend encodes business rules about what's possible, and the frontend simply renders what it receives.

Without HATEOAS, your frontend has code like this:

js
1// Frontend duplicates business logic
2if (order.status === 'Pending') {
3  showUpdateButton();
4  showCancelButton();
5} else if (order.status === 'Paid') {
6  showShipButton();
7}

With HATEOAS, your frontend becomes like this:

csharp
1// Frontend just checks for links
2if (order.links.find(l => l.rel === 'update')) {
3  showUpdateButton();
4}
5if (order.links.find(l => l.rel === 'ship')) {
6  showShipButton();
7}

When business rules change (for example, you decide Paid orders can still be updated for 24 hours), you only change the backend.

The frontend keeps working without any code changes. The key principle: your frontend doesn't hardcode URLs or duplicate business logic. It looks for links and renders UI based on what's available.

Let's explore how the OrderItemRow is rendered in a React frontend application:

tsx
1// components/OrderItemRow.tsx
2import React from 'react';
3import { OrderItem } from '../types/api';
4import { hasLink, findLink } from '../utils/linkHelper';
5import { apiClient } from '../services/apiClient';
6
7interface OrderItemRowProps {
8  item: OrderItem;
9  onUpdate: () => void;
10}
11
12export const OrderItemRow: React.FC<OrderItemRowProps> = ({ item, onUpdate }) => {
13  const handleUpdateQuantity = async () => {
14    const updateLink = findLink(item.links, 'update');
15    if (!updateLink) return;
16
17    const newQuantity = prompt('Enter new quantity:', item.quantity.toString());
18    if (!newQuantity) return;
19
20    try {
21      await apiClient.followLink(updateLink, {
22        quantity: parseInt(newQuantity),
23      });
24      onUpdate();
25    } catch (err) {
26      alert('Failed to update item');
27    }
28  };
29
30  const handleDelete = async () => {
31    const deleteLink = findLink(item.links, 'delete');
32    if (!deleteLink) return;
33
34    if (!confirm('Remove this item?')) return;
35
36    try {
37      await apiClient.followLink(deleteLink);
38      onUpdate();
39    } catch (err) {
40      alert('Failed to remove item');
41    }
42  };
43
44  return (
45    <div className="order-item-row">
46      <div className="item-info">
47        <span className="product-name">{item.productName}</span>
48        <span className="quantity">Qty: {item.quantity}</span>
49        <span className="price">${item.unitPrice.toFixed(2)}</span>
50        <span className="total">${item.lineTotal.toFixed(2)}</span>
51      </div>
52      
53      <div className="item-actions">
54        {hasLink(item.links, 'update') && (
55          <button onClick={handleUpdateQuantity}>Update</button>
56        )}
57        
58        {hasLink(item.links, 'delete') && (
59          <button onClick={handleDelete}>Remove</button>
60        )}
61      </div>
62    </div>
63  );
64};

You can make this even cleaner with a custom hook:

tsx
1// hooks/useHateoas.ts
2import { Link } from '../types/api';
3import { useMemo } from 'react';
4
5export const useHateoas = (links: Link[]) => {
6  const linkMap = useMemo(() => {
7    return links.reduce((acc, link) => {
8      acc[link.rel] = link;
9      return acc;
10    }, {} as Record<string, Link>);
11  }, [links]);
12
13  const hasAction = (rel: string): boolean => {
14    return rel in linkMap;
15  };
16
17  const getLink = (rel: string): Link | undefined => {
18    return linkMap[rel];
19  };
20
21  return { hasAction, getLink, links };
22};

Now your component becomes even simpler:

tsx
1export const OrderDetail: React.FC<OrderDetailProps> = ({ orderId }) => {
2  const [order, setOrder] = useState<Order | null>(null);
3  const { hasAction, getLink } = useHateoas(order?.links || []);
4
5  // ... other code ...
6
7  return (
8    <div className="order-actions">
9      {hasAction('update') && (
10        <button onClick={handleUpdate}>Update Order</button>
11      )}
12      {hasAction('delete') && (
13        <button onClick={handleDelete}>Cancel Order</button>
14      )}
15      {hasAction('ship') && (
16        <button onClick={handleShip}>Ship Order</button>
17      )}
18    </div>
19  );
20};

Your frontend becomes simpler. It says, "If there's an update link, show an update button," rather than "If the status is X or Y, show an update button." Business logic lives where it belongs: on the backend. The frontend focuses on presentation and user interaction.

When you add a new action, you add a new link on the backend and a new button check on the frontend. You don't need to synchronize complex state machines across multiple codebases.

This is what "Hypermedia as the Engine of Application State" actually means in practice. The API drives what's possible. The UI responds accordingly.

We've seen how HATEOAS works and how to implement it. Now let's be honest about when it's worth the effort and when you're better off skipping it.

HATEOAS isn't a silver bullet. Like any architectural decision, it comes with tradeoffs. Let's explore both sides.

1. Public APIs with Multiple Client Types

If you're building a public API consumed by web applications, mobile apps, and third-party integrations, HATEOAS shines. Different clients can follow different links. Links let you evolve your API without breaking clients. Mobile apps might run old versions for months.

2. Complex Workflow Systems

When your domain involves complex state machines with many possible transitions, HATEOAS keeps the logic centralized. Business rules about state transitions live on the backend. Frontend doesn't duplicate complex conditional logic. And rules can change without frontend updates.

3. Long-Lived APIs

If your API will exist for 5+ years and evolve significantly, HATEOAS provides flexibility. You can refactor URL structures without breaking clients. New actions can be added gradually. Deprecated actions can be removed gracefully. API becomes more discoverable for new developers.

1. Simple CRUD APIs

If your API is straightforward and involves create, read, update, and delete operations without complex workflows, HATEOAS is overkill. In such APIs, business rules are simple, with no complex state transitions to manage.

2. Internal APIs with Synchronized Deployments

If you control both frontend and backend, deploying them together, HATEOAS adds complexity without much benefit. You can update both sides simultaneously. And you get faster development with hardcoded URLs.

3. Performance-Critical Mobile APIs

Mobile applications on slow networks need small payloads.

Links add significant payload size to collections. If you're optimizing for every kilobyte, HATEOAS might not be worth it.

4. GraphQL or gRPC Systems

If you're using GraphQL or gRPC, you've already solved the problems HATEOAS addresses differently.

GraphQL gives a strongly-typed schema and lets clients query exactly what they need. gRPC also uses strongly-typed schemas.

Mixing paradigms creates confusion. Example scenario: You built a GraphQL API where clients compose queries. Adding HATEOAS links to GraphQL responses fights against GraphQL's design. Clients already specify what they want; they don't need the server suggesting actions.

You can also follow the pragmatic hybrid approach: Selective HATEOAS

Use HATEOAS only for resources with complex workflows:

• Orders with state transitions: Include links
• Simple product listings: No links
• User profiles: No links

Make links optional via query parameter:

bash
1GET /orders/123 - No links
2GET /orders/123?expand=links - Includes links

This lets performance-critical clients skip links.

Before deciding whether to stay at Level 2 or adopt HATEOAS, ask yourself: "Does HATEOAS solve a problem we actually have?"

If you're building an internal CRUD API with synchronized deployments, you don't have the problems HATEOAS solves. It's just extra work.

If you're building a public API with complex workflows consumed by many clients you don't control, HATEOAS might save you months of coordination and versioning headaches.

Architecture is about tradeoffs. HATEOAS trades implementation complexity and payload size for flexibility and loose coupling. Whether that trade makes sense depends entirely on your specific situation.

Hope you find this newsletter useful. See you next time.