Introduction

Ever wondered why most “REST APIs” aren’t actually RESTful? The missing piece is HATEOAS (Hypermedia as the Engine of Application State) - the most misunderstood and underutilized REST constraint.

HATEOAS transforms your API from a collection of endpoints into a self-documenting, discoverable system where clients navigate through hypermedia links rather than hardcoded URLs. Think of it like browsing the web: you don’t need to memorize URLs - you click links. HATEOAS brings this same principle to APIs.

What you’ll learn:

  • What HATEOAS actually means and why it matters
  • Practical implementation with Spring Boot and HAL+JSON
  • Real-world examples you can copy and adapt
  • Common mistakes developers make (and how to avoid them)
  • Modern tools and standards (OpenAPI, Spring HATEOAS)
  • When to use HATEOAS and when to skip it

What you’ll achieve:

  • APIs that evolve without breaking clients
  • Self-documenting services that reduce documentation burden
  • Looser coupling between client and server
  • Better developer experience for API consumers

Who this is for:

  • Backend developers building REST APIs
  • API architects designing scalable services
  • Teams struggling with API versioning
  • Anyone wanting to build truly RESTful services

Prerequisites:

  • Understanding of REST principles
  • Familiarity with JSON
  • Basic knowledge of HTTP methods (GET, POST, PUT, DELETE)

HATEOAS is a pivotal aspect of REST , as defined by Roy Fielding in his doctoral dissertation. Among the REST architectural constraints , HATEOAS is perhaps the most overlooked, yet it’s what truly distinguishes RESTful APIs from simple HTTP-based APIs.

What is Hypermedia

At its core, hypermedia is an extension of the concept of hypertext, familiar to most through HTML and the links that form the web. Hypermedia, however, goes beyond linking text documents, encompassing a wide range of media types (text, images, video, etc.) and enabling rich, non-linear navigation across these media. In the context of APIs, hypermedia refers to the inclusion of hyperlinks (or other navigational tools) within the API’s responses. These links guide clients through the available actions and resources, much like a web page includes links to other pages.

What is HATEOAS?

HATEOAS is what makes the REST architecture unique. It emphasizes that a client’s interaction with a server should be driven entirely through hypermedia provided dynamically by server responses. In simpler terms, the client does not need prior knowledge about how to interact with an application or server beyond a generic understanding of hypermedia. Each server response contains not just the data requested, but also controls, like hyperlinks, that the client can use to discover further actions and resources. This makes the client-server interaction more intuitive and self-explanatory.

Core Principles of HATEOAS

Dynamic Discovery of Actions: Unlike traditional APIs, where the possible actions are hardcoded into the client, HATEOAS requires that the client discovers available actions dynamically through hypermedia provided by the server. This means the client’s code does not have to change if the server’s interface changes, making the API more resilient and easier to evolve.

Decoupling Client and Server: By requiring the server to provide information on available actions, HATEOAS decouples the client from the server. The client doesn’t need to know the URI structure or have a hardcoded interaction pattern. This abstraction allows the server to evolve independently without impacting the client, as long as the hypermedia contract is respected.

Stateless Interactions: HATEOAS adheres to the statelessness constraint of REST, meaning that each request from the client contains all the information needed for the server to fulfill that request. The server doesn’t need to remember previous interactions. Coupled with HATEOAS, statelessness ensures that the server’s responses can guide the client through the application state without any need for the server to remember past requests.

Benefits of Using HATEOAS

Evolvability: Servers can evolve without impacting the clients. As long as the hypermedia controls are consistent, clients can navigate new versions of the API without changes.

Discoverability: Clients can discover actions and resources they might not have been coded to handle, leading to more robust and adaptable clients.

Self-Documentation: The use of standard hypermedia types means that responses can be self-descriptive. New developers or tools can understand the capabilities of the API by inspecting the hypermedia controls and relations provided in responses.

While the concept of HATEOAS can be abstract and its implementation challenging, its adherence is what separates truly RESTful APIs from the more common HTTP-based APIs. In the following sections, we’ll delve deeper into how HATEOAS is implemented, the challenges it presents, and the best practices to ensure your API not only meets the REST constraints but is also maintainable and scalable.

Components of HATEOAS

To effectively implement HATEOAS in a RESTful API, it’s crucial to understand its core components. These components work together to create a dynamic, self-descriptive, and navigable API. Here’s a breakdown of these essential elements:

Resources

Definition: In REST, a resource is any piece of information that can be named, whether it’s a document, an image, a temporal service (e.g., “today’s weather in London”), or a collection of other resources.Resources are identified by URLs (Uniform Resource Locators). However, the client does not need to know the URL structure; they discover URLs dynamically through hypermedia controls provided by the server. A resource can have one or more representations (e.g., JSON, XML, HTML). The server may provide the resource in a particular format depending on the client’s request (typically specified in the Accept header).

Hypermedia Controls

Links: One of the most critical aspects of HATEOAS is the use of hyperlinks. These links provide clients with the actions (or state transitions) that are currently available. For instance, in a response from a server, a resource representing a user might contain links to delete or update the user, or to fetch the user’s posts. Some RESTful designs also include forms (or templates) as part of their hypermedia controls. These forms instruct the client on how to submit data for resource creation or modification, similar to HTML forms in web pages.

Media Types

Definition: Media types (also known as MIME types) are standardized identifiers used to specify the format of a resource. They tell the client how the resource is structured and how to parse it. In the context of HATEOAS, media types can be used to describe the potential actions available to clients. For example, the application/vnd.collection+json media type indicates that the resource is a collection and that the client can expect certain standardized hypermedia controls within the payload.

Statelessness

While not a component in the direct sense, it’s crucial to remember that HATEOAS operates under the REST constraint of statelessness. This means that each client request must contain all the information the server needs to fulfill that request, and the server should not need to remember previous interactions. Hypermedia controls guide the client through the application states, with each client request being an independent interaction.

Understanding these components is essential for designing and implementing a RESTful API that truly adheres to the HATEOAS constraint. It’s not just about structuring data but about creating a self-descriptive, navigable, and flexible web service that empowers clients to interact with the server dynamically and discover available actions on the fly. In the next section, we’ll explore how these components come together in practice, providing a guide on implementing HATEOAS in your RESTful APIs.

Implementing HATEOAS in RESTful APIs

Implementing HATEOAS can initially seem daunting due to its dynamic nature and the shift from traditional API designs. However, with a structured approach, you can effectively incorporate HATEOAS principles into your RESTful APIs. Here’s how you can go about it:

  • Designing Resource Identifiers (URIs) : Start by clearly defining your resources and designing intuitive and consistent URIs for them. Although HATEOAS allows clients to discover URIs dynamically, having a well-thought-out URI structure is crucial for maintainability and clarity.

  • Choosing the Right Media Type : Select a media type that supports hypermedia. Options include application/hal+json, application/vnd.collection+json, or custom media types. Ensure that the media type you choose or design adequately supports linking to other resources and actions.

  • Structuring Responses with Links : Craft your API responses to include not just the requested data, but also links that indicate what the client can do next. These links should be dynamic, reflecting the state of the resource. For instance, if a resource can no longer be deleted (perhaps because it has already been deleted), the link to the delete action should not be present.


{
  "userId": "12345",
  "name": "John Doe",
  "links": [
    {"rel": "self", "href": "/users/12345"},
    {"rel": "posts", "href": "/users/12345/posts"}
  ]
}

  • Implementing Hypermedia Controls Beyond Links : Consider implementing more sophisticated hypermedia controls, such as forms for creating or updating resources. This can guide the client on the expected input, making your API more self-descriptive and user-friendly.

  • Handling State Transitions : Ensure that your API responses guide the client through the state transitions. The presence or absence of certain links can indicate the current state of a resource and the actions that are possible at this stage.

  • Versioning Your API : Even with HATEOAS, you might need to version your API. Ensure that you handle versioning in a way that does not disrupt the client’s ability to navigate your API. Embedding version information within the media type or using URI paths are common approaches.

Challenges and Considerations of implementing HATEOAS

While implementing HATEOAS, you might encounter several challenges:

  • Client Complexity: Clients consuming a HATEOAS-driven API might become more complex, as they need to understand and interpret hypermedia controls.
  • Documentation: Properly documenting a HATEOAS API can be challenging since the available actions are dynamic and context-dependent.
  • Performance: Adding links and controls can increase the payload size and require additional processing on the server.

To mitigate these challenges, focus on clear documentation, consider the trade-offs between payload size and navigability, and provide client libraries or SDKs if possible to abstract some of the HATEOAS complexity.

Implementing HATEOAS is a commitment to building a truly RESTful API that is scalable, flexible, and maintainable. It requires a shift in mindset from both API developers and consumers but offers significant benefits in terms of the loose coupling of client and server and the ability to evolve the API over time without breaking contracts.

In the next section, we’ll discuss some best practices to ensure your implementation of HATEOAS is robust and effective.

Best Practices for Implementing HATEOAS

Implementing HATEOAS in your RESTful APIs can significantly enhance the flexibility and scalability of your services. However, to reap the full benefits, it’s essential to adhere to best practices that ensure your API is intuitive and maintainable. Here are some key guidelines:

  • Clear and Consistent Link Relations : Use standardized link relations where possible, and ensure custom relations are clear and well-documented. Consistent use of link relations helps clients understand and navigate your API effectively.

  • Use of Standardized Media Types : Prefer standardized media types like application/hal+json or application/vnd.collection+json. These media types are widely recognized and understood, and they provide a consistent structure for embedding links and actions.

  • Descriptive Linking : Links should be descriptive and indicate their purpose clearly. Clients should be able to understand the semantics of a link relation without needing to refer to documentation constantly. For example, a link with the relation next in a paginated list implies that following the link retrieves the next page of results.

  • Embedding Links When Necessary : Embed links in your resource representations judiciously. While it’s crucial to provide navigational links, overloading a response with links can make it cumbersome. Balance is key – provide links that are necessary for the client to understand the possible state transitions and actions.

  • Documentation and Discovery : Although HATEOAS promotes discoverability through hypermedia, comprehensive documentation is still crucial. Document your API’s resources, possible states, and transitions, and how the links relate to these states. Consider providing a machine-readable API description format like OpenAPI (formerly Swagger) or API Blueprint. These can help clients understand your API structure and can also be used to generate documentation or client SDKs automatically.

  • Client Education and SDKs : Educate your API consumers about the principles of HATEOAS and how to interact with a HATEOAS-driven API. Clear examples and tutorials can significantly reduce the learning curve. Provide client libraries or SDKs if possible. These can abstract some of the complexities of HATEOAS and offer a more straightforward interface for clients to interact with your API.

  • Performance Considerations : Be mindful of the size of your responses. Hypermedia controls can increase the size of your payload, which may impact performance. Use techniques like pagination, link expansion options, or HTTP/2 to mitigate these issues.

  • Versioning and Evolvability : Design your API with evolvability in mind. HATEOAS allows you to evolve your API without breaking client integrations, but this requires careful planning and clear communication with your API consumers.

  • Testing HATEOAS Aspects : Ensure that your automated tests cover the dynamic aspects of your HATEOAS implementation. Test that your links appear as expected in different states and that they correctly reflect the possible actions and transitions.

Implementing these best practices will help ensure that your HATEOAS-driven API is not just compliant with REST principles but is also practical, intuitive, and resilient to changes. In the next section, we will explore some real-world examples and case studies to understand how HATEOAS is implemented in practice and the benefits it brings.

Practical Implementation with Spring Boot

Let’s implement a real-world HATEOAS API using Spring Boot and Spring HATEOAS framework. We’ll build a simple blog API that demonstrates key HATEOAS concepts.

Setting Up Dependencies

First, add Spring HATEOAS to your pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-hateoas</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Domain Model

@Entity
public class BlogPost {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String title;
    private String content;
    private String author;

    @Enumerated(EnumType.STRING)
    private PostStatus status; // DRAFT, PUBLISHED, ARCHIVED

    private LocalDateTime createdAt;
    private LocalDateTime publishedAt;

    // Getters and setters omitted for brevity
}

public enum PostStatus {
    DRAFT, PUBLISHED, ARCHIVED
}

Resource Representation Model

Spring HATEOAS uses RepresentationModel to add hypermedia links:

public class BlogPostModel extends RepresentationModel<BlogPostModel> {
    private Long id;
    private String title;
    private String content;
    private String author;
    private PostStatus status;
    private LocalDateTime createdAt;
    private LocalDateTime publishedAt;

    // Constructors, getters, and setters
}

Model Assembler

The assembler converts entities to HATEOAS models with links:

@Component
public class BlogPostModelAssembler
    implements RepresentationModelAssembler<BlogPost, BlogPostModel> {

    @Override
    public BlogPostModel toModel(BlogPost post) {
        BlogPostModel model = new BlogPostModel();
        // Copy properties from entity
        model.setId(post.getId());
        model.setTitle(post.getTitle());
        model.setContent(post.getContent());
        model.setAuthor(post.getAuthor());
        model.setStatus(post.getStatus());
        model.setCreatedAt(post.getCreatedAt());
        model.setPublishedAt(post.getPublishedAt());

        // Add self link
        model.add(linkTo(methodOn(BlogPostController.class)
            .getPost(post.getId()))
            .withSelfRel());

        // Add conditional links based on state
        if (post.getStatus() == PostStatus.DRAFT) {
            model.add(linkTo(methodOn(BlogPostController.class)
                .publishPost(post.getId()))
                .withRel("publish"));

            model.add(linkTo(methodOn(BlogPostController.class)
                .updatePost(post.getId(), null))
                .withRel("update"));

            model.add(linkTo(methodOn(BlogPostController.class)
                .deletePost(post.getId()))
                .withRel("delete"));
        }

        if (post.getStatus() == PostStatus.PUBLISHED) {
            model.add(linkTo(methodOn(BlogPostController.class)
                .archivePost(post.getId()))
                .withRel("archive"));

            // Published posts can only be updated, not deleted
            model.add(linkTo(methodOn(BlogPostController.class)
                .updatePost(post.getId(), null))
                .withRel("update"));
        }

        if (post.getStatus() == PostStatus.ARCHIVED) {
            model.add(linkTo(methodOn(BlogPostController.class)
                .republishPost(post.getId()))
                .withRel("republish"));
        }

        // Add link to author
        model.add(linkTo(methodOn(AuthorController.class)
            .getAuthor(post.getAuthor()))
            .withRel("author"));

        // Add link to comments
        model.add(linkTo(methodOn(CommentController.class)
            .getComments(post.getId()))
            .withRel("comments"));

        return model;
    }
}

REST Controller

@RestController
@RequestMapping("/api/posts")
public class BlogPostController {

    @Autowired
    private BlogPostService postService;

    @Autowired
    private BlogPostModelAssembler assembler;

    @GetMapping("/{id}")
    public EntityModel<BlogPostModel> getPost(@PathVariable Long id) {
        BlogPost post = postService.findById(id)
            .orElseThrow(() -> new ResourceNotFoundException("Post not found"));

        return EntityModel.of(assembler.toModel(post));
    }

    @GetMapping
    public CollectionModel<BlogPostModel> getAllPosts(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "10") int size) {

        Page<BlogPost> postsPage = postService.findAll(
            PageRequest.of(page, size));

        List<BlogPostModel> posts = postsPage.getContent().stream()
            .map(assembler::toModel)
            .collect(Collectors.toList());

        CollectionModel<BlogPostModel> collection =
            CollectionModel.of(posts);

        // Add pagination links
        collection.add(linkTo(methodOn(BlogPostController.class)
            .getAllPosts(page, size))
            .withSelfRel());

        if (page > 0) {
            collection.add(linkTo(methodOn(BlogPostController.class)
                .getAllPosts(page - 1, size))
                .withRel("prev"));
        }

        if (page < postsPage.getTotalPages() - 1) {
            collection.add(linkTo(methodOn(BlogPostController.class)
                .getAllPosts(page + 1, size))
                .withRel("next"));
        }

        collection.add(linkTo(methodOn(BlogPostController.class)
            .getAllPosts(0, size))
            .withRel("first"));

        collection.add(linkTo(methodOn(BlogPostController.class)
            .getAllPosts(postsPage.getTotalPages() - 1, size))
            .withRel("last"));

        return collection;
    }

    @PostMapping
    public ResponseEntity<BlogPostModel> createPost(
        @RequestBody BlogPostRequest request) {

        BlogPost post = postService.create(request);
        BlogPostModel model = assembler.toModel(post);

        return ResponseEntity
            .created(model.getRequiredLink("self").toUri())
            .body(model);
    }

    @PutMapping("/{id}")
    public ResponseEntity<BlogPostModel> updatePost(
        @PathVariable Long id,
        @RequestBody BlogPostRequest request) {

        BlogPost post = postService.update(id, request);
        BlogPostModel model = assembler.toModel(post);

        return ResponseEntity.ok(model);
    }

    @PostMapping("/{id}/publish")
    public ResponseEntity<BlogPostModel> publishPost(@PathVariable Long id) {
        BlogPost post = postService.publish(id);
        BlogPostModel model = assembler.toModel(post);

        return ResponseEntity.ok(model);
    }

    @PostMapping("/{id}/archive")
    public ResponseEntity<BlogPostModel> archivePost(@PathVariable Long id) {
        BlogPost post = postService.archive(id);
        BlogPostModel model = assembler.toModel(post);

        return ResponseEntity.ok(model);
    }

    @PostMapping("/{id}/republish")
    public ResponseEntity<BlogPostModel> republishPost(@PathVariable Long id) {
        BlogPost post = postService.republish(id);
        BlogPostModel model = assembler.toModel(post);

        return ResponseEntity.ok(model);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<?> deletePost(@PathVariable Long id) {
        postService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

HAL+JSON Response Examples

When you request a draft post (GET /api/posts/1):

{
  "id": 1,
  "title": "Getting Started with HATEOAS",
  "content": "HATEOAS is a constraint of REST...",
  "author": "john.doe",
  "status": "DRAFT",
  "createdAt": "2025-01-01T10:00:00",
  "publishedAt": null,
  "_links": {
    "self": {
      "href": "http://localhost:8080/api/posts/1"
    },
    "publish": {
      "href": "http://localhost:8080/api/posts/1/publish"
    },
    "update": {
      "href": "http://localhost:8080/api/posts/1"
    },
    "delete": {
      "href": "http://localhost:8080/api/posts/1"
    },
    "author": {
      "href": "http://localhost:8080/api/authors/john.doe"
    },
    "comments": {
      "href": "http://localhost:8080/api/posts/1/comments"
    }
  }
}

Notice how the response includes links for publish, update, and delete - these are the actions available for a draft post.

When you request a published post (GET /api/posts/2):

{
  "id": 2,
  "title": "Advanced HATEOAS Patterns",
  "content": "Let's explore advanced patterns...",
  "author": "jane.smith",
  "status": "PUBLISHED",
  "createdAt": "2024-12-15T09:30:00",
  "publishedAt": "2024-12-16T14:00:00",
  "_links": {
    "self": {
      "href": "http://localhost:8080/api/posts/2"
    },
    "archive": {
      "href": "http://localhost:8080/api/posts/2/archive"
    },
    "update": {
      "href": "http://localhost:8080/api/posts/2"
    },
    "author": {
      "href": "http://localhost:8080/api/authors/jane.smith"
    },
    "comments": {
      "href": "http://localhost:8080/api/posts/2/comments"
    }
  }
}

Notice the differences: Published posts have archive and update links, but no delete or publish links - because those actions aren’t valid for a published post.

A collection response with pagination (GET /api/posts?page=1&size=10):

{
  "_embedded": {
    "blogPostModelList": [
      {
        "id": 11,
        "title": "Post Title 11",
        "status": "PUBLISHED",
        "_links": {
          "self": {"href": "http://localhost:8080/api/posts/11"},
          "archive": {"href": "http://localhost:8080/api/posts/11/archive"}
        }
      },
      {
        "id": 12,
        "title": "Post Title 12",
        "status": "DRAFT",
        "_links": {
          "self": {"href": "http://localhost:8080/api/posts/12"},
          "publish": {"href": "http://localhost:8080/api/posts/12/publish"}
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "http://localhost:8080/api/posts?page=1&size=10"
    },
    "first": {
      "href": "http://localhost:8080/api/posts?page=0&size=10"
    },
    "prev": {
      "href": "http://localhost:8080/api/posts?page=0&size=10"
    },
    "next": {
      "href": "http://localhost:8080/api/posts?page=2&size=10"
    },
    "last": {
      "href": "http://localhost:8080/api/posts?page=5&size=10"
    }
  },
  "page": {
    "size": 10,
    "totalElements": 57,
    "totalPages": 6,
    "number": 1
  }
}

Client Implementation Example

Here’s how a client would consume this HATEOAS API:

public class BlogClient {
    private final RestTemplate restTemplate;
    private final String baseUrl;

    public void publishDraftPosts() {
        // Start from the root - no hardcoded URLs needed
        String postsUrl = baseUrl + "/api/posts";

        // Get all posts
        CollectionModel<BlogPostModel> posts =
            restTemplate.getForObject(postsUrl,
                new ParameterizedTypeReference<CollectionModel<BlogPostModel>>() {});

        // Process each post
        for (BlogPostModel post : posts.getContent()) {
            // Check if the post CAN be published by looking for the "publish" link
            Link publishLink = post.getLink("publish");

            if (publishLink.isPresent()) {
                // The link exists, so publishing is allowed
                restTemplate.postForObject(
                    publishLink.get().getHref(),
                    null,
                    BlogPostModel.class);

                System.out.println("Published post: " + post.getTitle());
            } else {
                // No publish link means this action isn't available
                System.out.println("Cannot publish post: " + post.getTitle()
                    + " (status: " + post.getStatus() + ")");
            }
        }
    }
}

Key point: The client doesn’t hardcode business logic like “only draft posts can be published”. Instead, it discovers available actions through hypermedia links. If the server’s business rules change, the client continues to work without modifications.

For domain-specific actions, define custom link relations:

public class CustomLinkRelations {
    public static final String APPROVE = "approve";
    public static final String REJECT = "reject";
    public static final String REQUEST_REVIEW = "request-review";
}

// In your assembler
if (post.getStatus() == PostStatus.PENDING_REVIEW) {
    model.add(linkTo(methodOn(BlogPostController.class)
        .approvePost(post.getId()))
        .withRel(CustomLinkRelations.APPROVE));

    model.add(linkTo(methodOn(BlogPostController.class)
        .rejectPost(post.getId()))
        .withRel(CustomLinkRelations.REJECT));
}

Integration with OpenAPI/Swagger

You can document your HATEOAS API with OpenAPI:

@Configuration
public class OpenAPIConfig {

    @Bean
    public OpenAPI blogApiOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("Blog API with HATEOAS")
                .version("v1.0")
                .description("RESTful blog API implementing HATEOAS constraints")
                .contact(new Contact()
                    .name("API Support")
                    .email("support@example.com")))
            .servers(List.of(
                new Server().url("http://localhost:8080")
                    .description("Development server")))
            .components(new Components()
                .schemas(Map.of(
                    "BlogPost", new Schema<>()
                        .description("Blog post with hypermedia links")
                        .addProperty("_links", new Schema<>()
                            .description("Hypermedia links showing available actions"))
                )));
    }
}

This Spring Boot example demonstrates:

  • State-driven links: Links change based on resource state (draft vs. published)
  • Self-documentation: Clients discover actions through _links
  • Loose coupling: Clients don’t hardcode URLs or business rules
  • HAL+JSON format: Industry-standard hypermedia format
  • Pagination: Proper navigation through collections
  • OpenAPI integration: Documentation that coexists with HATEOAS

Common Mistakes When Implementing HATEOAS

Even experienced developers make mistakes when implementing HATEOAS. Here are the most common pitfalls and how to avoid them:

The Mistake:

{
  "id": 123,
  "status": "PUBLISHED",
  "_links": {
    "self": {"href": "/posts/123"},
    "publish": {"href": "/posts/123/publish"},  // WRONG: Already published!
    "delete": {"href": "/posts/123"}            // WRONG: Can't delete published posts
  }
}

Why It’s Wrong: The response includes publish and delete links even though the post is already published. This violates the HATEOAS principle - links should only represent currently available actions.

The Fix:

// In your model assembler
public BlogPostModel toModel(BlogPost post) {
    BlogPostModel model = new BlogPostModel();
    // ... copy properties ...

    // Add self link (always present)
    model.add(linkTo(methodOn(BlogPostController.class)
        .getPost(post.getId())).withSelfRel());

    // Add state-specific links
    switch (post.getStatus()) {
        case DRAFT:
            model.add(linkTo(methodOn(BlogPostController.class)
                .publishPost(post.getId())).withRel("publish"));
            model.add(linkTo(methodOn(BlogPostController.class)
                .deletePost(post.getId())).withRel("delete"));
            break;

        case PUBLISHED:
            model.add(linkTo(methodOn(BlogPostController.class)
                .archivePost(post.getId())).withRel("archive"));
            // No delete link for published posts
            break;

        case ARCHIVED:
            model.add(linkTo(methodOn(BlogPostController.class)
                .republishPost(post.getId())).withRel("republish"));
            break;
    }

    return model;
}

Result: Links accurately reflect what the client can actually do right now.

2. Hardcoding URLs in Client Code

The Mistake:

// BAD: Client hardcodes URL structure
public class BlogClient {
    public void publishPost(Long postId) {
        String url = "http://api.example.com/api/posts/" + postId + "/publish";
        restTemplate.postForObject(url, null, BlogPostModel.class);
    }
}

Why It’s Wrong: This defeats the entire purpose of HATEOAS. The client is tightly coupled to the server’s URL structure. If the server changes from /posts/{id}/publish to /posts/{id}/actions/publish, the client breaks.

The Fix:

// GOOD: Client follows hypermedia links
public class BlogClient {
    public void publishPost(BlogPostModel post) {
        Link publishLink = post.getLink("publish")
            .orElseThrow(() -> new IllegalStateException(
                "Cannot publish post - action not available"));

        restTemplate.postForObject(
            publishLink.getHref(),
            null,
            BlogPostModel.class);
    }
}

Result: The client discovers the URL dynamically. Server can change URL structure without breaking clients.

The Mistake:

{
  "_links": {
    "action1": {"href": "/posts/123/publish"},
    "action2": {"href": "/posts/123/archive"},
    "related": {"href": "/authors/jane"}
  }
}

Why It’s Wrong: Generic relation names like action1, action2, related provide no semantic meaning. Clients have no idea what these links do without external documentation.

The Fix:

{
  "_links": {
    "publish": {"href": "/posts/123/publish"},
    "archive": {"href": "/posts/123/archive"},
    "author": {"href": "/authors/jane"},
    "comments": {"href": "/posts/123/comments"}
  }
}

Use standard IANA link relations where applicable:

  • self - The current resource
  • next/prev - Pagination
  • first/last - Collection boundaries
  • edit - Where to update the resource
  • related - Related resources

For custom relations, use descriptive names that convey intent: publish, archive, approve, reject.

The Mistake:

// Endpoint 1 returns links like this:
{
  "_links": {
    "author": "/authors/123"
  }
}

// Endpoint 2 returns links like this:
{
  "links": [
    {"rel": "author", "href": "/authors/123"}
  ]
}

Why It’s Wrong: Inconsistent link formats confuse clients and make parsing difficult. Each client request might return a different structure.

The Fix: Choose a standard media type and stick with it consistently:

// Always use HAL+JSON format across all endpoints
@GetMapping(produces = MediaTypes.HAL_JSON_VALUE)
public EntityModel<BlogPostModel> getPost(@PathVariable Long id) {
    // Returns consistent HAL+JSON structure
}

@GetMapping(produces = MediaTypes.HAL_JSON_VALUE)
public CollectionModel<BlogPostModel> getAllPosts() {
    // Also returns HAL+JSON
}

Result: Every response uses the same hypermedia format, making client code simpler and more reliable.

The Mistake:

// Client assumes link always exists
public void archivePost(BlogPostModel post) {
    Link archiveLink = post.getLink("archive").get(); // Throws if missing!
    restTemplate.postForObject(archiveLink.getHref(), null, Void.class);
}

Why It’s Wrong: Links may not exist based on resource state. This code crashes when the archive link is missing (e.g., for draft posts).

The Fix:

// Option 1: Check presence first
public boolean archivePost(BlogPostModel post) {
    Optional<Link> archiveLink = post.getLink("archive");

    if (archiveLink.isPresent()) {
        restTemplate.postForObject(
            archiveLink.get().getHref(),
            null,
            Void.class);
        return true;
    } else {
        log.warn("Cannot archive post {} - action not available", post.getId());
        return false;
    }
}

// Option 2: Use orElseThrow with meaningful message
public void archivePost(BlogPostModel post) {
    Link archiveLink = post.getLink("archive")
        .orElseThrow(() -> new IllegalStateException(
            "Post cannot be archived in its current state: " + post.getStatus()));

    restTemplate.postForObject(archiveLink.getHref(), null, Void.class);
}

Result: Graceful handling of missing links with clear error messages.

The Mistake:

{
  "id": 123,
  "title": "My Post",
  "_links": {
    "self": {"href": "/posts/123"},
    "update": {"href": "/posts/123"},
    "delete": {"href": "/posts/123"},
    "publish": {"href": "/posts/123/publish"},
    "author": {"href": "/authors/jane"},
    "author-profile": {"href": "/authors/jane/profile"},
    "author-posts": {"href": "/authors/jane/posts"},
    "comments": {"href": "/posts/123/comments"},
    "comment-count": {"href": "/posts/123/comments/count"},
    "latest-comment": {"href": "/posts/123/comments/latest"},
    "tags": {"href": "/posts/123/tags"},
    "category": {"href": "/categories/tech"},
    "related-posts": {"href": "/posts/123/related"},
    "statistics": {"href": "/posts/123/stats"}
    // ... 20 more links ...
  }
}

Why It’s Wrong: Too many links bloat the response, confuse clients, and impact performance. Many of these links aren’t immediately useful.

The Fix: Include only essential and actionable links:

{
  "id": 123,
  "title": "My Post",
  "_links": {
    "self": {"href": "/posts/123"},
    "publish": {"href": "/posts/123/publish"},
    "update": {"href": "/posts/123"},
    "delete": {"href": "/posts/123"},
    "author": {"href": "/authors/jane"},
    "comments": {"href": "/posts/123/comments"}
  }
}

For related resources that aren’t immediately needed, let clients discover them by following the initial links. For example, clients can get author-posts by first following the author link.

The Mistake: Creating custom link relations like x-approve, x-submit-review without documenting what they mean or how to use them.

The Fix:

// 1. Create a link relations registry
public class LinkRelations {
    public static final String APPROVE = "approve";
    public static final String REJECT = "reject";

    // Document each relation
    /**
     * Link relation: approve
     * Method: POST
     * Description: Approves a pending blog post for publication
     * Preconditions: Post must be in PENDING_REVIEW status
     * Effect: Changes post status to APPROVED
     */
    public static final LinkRelation APPROVE_REL =
        LinkRelation.of(APPROVE);
}

// 2. Use OpenAPI to document relations
@Operation(
    summary = "Approve post",
    description = "Approves a blog post that is pending review"
)
@ApiResponse(responseCode = "200", description = "Post approved")
@ApiResponse(responseCode = "409", description = "Post not in reviewable state")
@PostMapping("/{id}/approve")
public ResponseEntity<BlogPostModel> approvePost(@PathVariable Long id) {
    // Implementation
}

Result: Developers consuming your API understand what each link relation means and how to use it.

The Mistake:

// Controller doing too much
@GetMapping("/{id}")
public EntityModel<BlogPostModel> getPost(@PathVariable Long id) {
    BlogPost post = postService.findById(id);
    BlogPostModel model = new BlogPostModel(post);

    // Business logic scattered in controller
    if (post.getStatus() == PostStatus.DRAFT) {
        model.add(Link.of("/posts/" + id + "/publish", "publish"));
    }
    if (securityService.hasRole("ADMIN")) {
        model.add(Link.of("/posts/" + id + "/delete", "delete"));
    }
    // More conditions...

    return EntityModel.of(model);
}

Why It’s Wrong: Business logic is scattered, hard to test, and violates single responsibility principle.

The Fix: Centralize link generation in model assemblers:

@Component
public class BlogPostModelAssembler
    implements RepresentationModelAssembler<BlogPost, BlogPostModel> {

    @Autowired
    private SecurityService securityService;

    @Override
    public BlogPostModel toModel(BlogPost post) {
        BlogPostModel model = createModel(post);
        addSelfLink(model, post);
        addStateTransitionLinks(model, post);
        addSecurityBasedLinks(model, post);
        addRelatedResourceLinks(model, post);
        return model;
    }

    private void addStateTransitionLinks(BlogPostModel model, BlogPost post) {
        if (post.getStatus() == PostStatus.DRAFT) {
            model.add(linkTo(methodOn(BlogPostController.class)
                .publishPost(post.getId())).withRel("publish"));
        }
        // More state-based logic...
    }

    private void addSecurityBasedLinks(BlogPostModel model, BlogPost post) {
        if (securityService.canDelete(post)) {
            model.add(linkTo(methodOn(BlogPostController.class)
                .deletePost(post.getId())).withRel("delete"));
        }
    }
}

Result: Clean separation of concerns, easier testing, and maintainable code.

Quick Checklist: Avoiding HATEOAS Mistakes

Before deploying your HATEOAS API, verify:

  • ✅ Links reflect current resource state (no impossible actions)
  • ✅ Clients follow links, not hardcoded URLs
  • ✅ Link relations are semantic and documented
  • ✅ Consistent hypermedia format across all endpoints
  • ✅ Client code handles missing links gracefully
  • ✅ Response payload isn’t bloated with unnecessary links
  • ✅ Custom link relations are documented
  • ✅ Link generation is centralized in assemblers/builders
  • ✅ Tests verify links appear/disappear based on state
  • ✅ OpenAPI/Swagger documents hypermedia aspects

Frequently Asked Questions

What does HATEOAS stand for?

HATEOAS stands for Hypermedia as the Engine of Application State. It’s a constraint of REST architecture that requires server responses to include hypermedia links that guide clients through available actions and state transitions. Instead of clients needing to know all API endpoints upfront, they discover what they can do by following links provided in each response, similar to how you navigate websites by clicking links.

Is HATEOAS required for a REST API?

Yes, according to Roy Fielding’s original REST architectural definition, HATEOAS is required for an API to be truly RESTful. However, many APIs marketed as “REST APIs” don’t implement HATEOAS and are more accurately described as HTTP-based APIs. While you can build functional APIs without HATEOAS, you lose key benefits like:

  • Evolvability: Server can change URLs without breaking clients
  • Discoverability: Clients discover capabilities dynamically
  • Loose coupling: Clients don’t hardcode business rules or URL structures
  • Self-documentation: Available actions are clear from the response

Whether to implement HATEOAS depends on your needs. For public APIs with many independent clients or long-lived integrations, HATEOAS provides significant value. For internal microservices or simple CRUD APIs, the added complexity may not be worth it.

What is HAL+JSON and why use it for HATEOAS?

HAL+JSON (Hypertext Application Language) is a standardized media type (application/hal+json) for representing resources with embedded links and other resources. It provides a consistent structure for HATEOAS APIs:

{
  "id": 123,
  "title": "Blog Post",
  "_links": {
    "self": {"href": "/posts/123"},
    "author": {"href": "/authors/jane"}
  },
  "_embedded": {
    "comments": [
      {"id": 1, "text": "Great post!"}
    ]
  }
}

Why use HAL+JSON:

  • Standardization: Widely recognized format with client library support
  • Simplicity: Easy to understand and implement
  • Tooling: Many frameworks (like Spring HATEOAS) have built-in HAL support
  • Documentation: OpenAPI can describe HAL+JSON responses
  • Embedding: Supports embedding related resources to reduce API calls

Alternatives include JSON:API, Collection+JSON, and Siren, but HAL+JSON offers the best balance of simplicity and adoption.

How do I implement HATEOAS in Spring Boot?

Spring Boot makes HATEOAS implementation straightforward with the Spring HATEOAS library:

1. Add dependency:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-hateoas</artifactId>
</dependency>

2. Create a model assembler:

@Component
public class UserModelAssembler
    implements RepresentationModelAssembler<User, EntityModel<User>> {

    @Override
    public EntityModel<User> toModel(User user) {
        return EntityModel.of(user,
            linkTo(methodOn(UserController.class).getUser(user.getId())).withSelfRel(),
            linkTo(methodOn(UserController.class).getAllUsers()).withRel("users"));
    }
}

3. Use in controller:

@GetMapping("/{id}")
public EntityModel<User> getUser(@PathVariable Long id) {
    User user = repository.findById(id).orElseThrow();
    return assembler.toModel(user);
}

This produces HAL+JSON responses with hypermedia links automatically.

When should I NOT use HATEOAS?

HATEOAS adds complexity, so skip it when:

1. Simple internal microservices: If you control both client and server and they’re deployed together, HATEOAS overhead may not be worth it.

2. High-performance requirements: Hypermedia links increase response payload size. For ultra-high-performance APIs where every byte matters, this can be problematic.

3. Simple CRUD operations: For straightforward create/read/update/delete APIs with no complex state transitions, HATEOAS provides little benefit.

4. Short-lived integrations: If your API has a short lifespan or clients are frequently updated in lockstep with the server, loose coupling isn’t critical.

5. Non-REST paradigms: If you’re building GraphQL, gRPC, or other non-REST APIs, HATEOAS doesn’t apply.

When TO use HATEOAS:

  • Public APIs with unknown clients
  • Long-lived APIs that need to evolve
  • Complex state machines with many transitions
  • APIs where discoverability is valuable
  • When you want true REST compliance

What’s the difference between HATEOAS and just returning URLs?

Many developers think adding URLs to JSON responses equals HATEOAS. The key differences:

Just URLs (NOT HATEOAS):

{
  "userId": 123,
  "name": "John",
  "profileUrl": "/users/123/profile",
  "postsUrl": "/users/123/posts"
}

Problems:

  • URLs are static - always present regardless of state
  • No semantic meaning (what’s the relationship?)
  • No indication of HTTP method to use
  • Clients still need to know business rules

True HATEOAS:

{
  "userId": 123,
  "name": "John",
  "_links": {
    "self": {"href": "/users/123"},
    "profile": {"href": "/users/123/profile"},
    "posts": {"href": "/users/123/posts"},
    "delete": {"href": "/users/123"}
  }
}

If user is deleted, response changes:

{
  "userId": 123,
  "name": "John",
  "status": "deleted",
  "_links": {
    "self": {"href": "/users/123"},
    "restore": {"href": "/users/123/restore"}
  }
}

Key differences:

  • Dynamic: Links appear/disappear based on state
  • Semantic: Link relations convey meaning (delete, restore)
  • Standardized format: Uses HAL, JSON:API, or other standards
  • Drives client behavior: Clients check for link presence, not state values

How do I version a HATEOAS API?

Versioning HATEOAS APIs requires balancing evolvability with breaking changes. Best approaches:

1. Media Type Versioning (Recommended):

Accept: application/vnd.myapi.v2+json

Advantages: Links remain discoverable, version is separate from URLs

2. Embed version in link relations:

{
  "_links": {
    "self": {"href": "/users/123"},
    "v2:advanced-profile": {"href": "/v2/users/123/profile"}
  }
}

3. Avoid breaking changes: HATEOAS’s strength is evolvability. Instead of versions:

  • Add new link relations without removing old ones
  • Add optional fields without changing existing ones
  • Deprecate links gradually with warnings

What NOT to do:

/v1/users/123  ❌ (URL-based versioning defeats HATEOAS discoverability)

Example evolution without breaking changes:

// Version 1
{
  "_links": {
    "profile": {"href": "/users/123/profile"}
  }
}

// Version 2 (adds new capability, keeps old)
{
  "_links": {
    "profile": {"href": "/users/123/profile"},
    "detailed-profile": {"href": "/users/123/profile/detailed"}
  }
}

Can I use HATEOAS with microservices?

Yes, but with considerations:

Benefits:

  • Service discovery: Services discover each other’s capabilities dynamically
  • Resilience: Clients adapt to service changes without redeployment
  • API gateway integration: Gateway can aggregate and transform links
  • Loose coupling: Services evolve independently

Challenges:

  • Performance: Extra payload for links in high-volume inter-service calls
  • Complexity: More sophisticated clients needed
  • Latency: Following links means additional HTTP calls

Best practices for microservices:

  1. Use HATEOAS selectively: Public-facing aggregation layer uses HATEOAS; internal high-performance services may skip it

  2. Embed related resources: Reduce round trips by embedding frequently-needed data:

{
  "orderId": 123,
  "_embedded": {
    "customer": {"id": 456, "name": "John"}
  },
  "_links": {
    "payment": {"href": "/payments/789"}
  }
}

  1. Service mesh integration: Use service mesh for discovery; HATEOAS for application-level navigation

  2. GraphQL alternative: For internal services, GraphQL may be simpler than HATEOAS

How do I test HATEOAS APIs?

Testing HATEOAS requires verifying both data and hypermedia controls:

1. Unit tests for link generation:

@Test
public void draftPostShouldHavePublishLink() {
    BlogPost draft = new BlogPost();
    draft.setStatus(PostStatus.DRAFT);

    BlogPostModel model = assembler.toModel(draft);

    assertTrue(model.getLink("publish").isPresent());
    assertFalse(model.getLink("archive").isPresent());
}

@Test
public void publishedPostShouldHaveArchiveLink() {
    BlogPost published = new BlogPost();
    published.setStatus(PostStatus.PUBLISHED);

    BlogPostModel model = assembler.toModel(published);

    assertTrue(model.getLink("archive").isPresent());
    assertFalse(model.getLink("publish").isPresent());
}

2. Integration tests following links:

@Test
public void shouldPublishDraftPostByFollowingLink() {
    // Create draft
    EntityModel<BlogPost> draft = restTemplate.getForObject("/posts/1", ...);

    // Extract publish link
    Link publishLink = draft.getRequiredLink("publish");

    // Follow link to publish
    restTemplate.postForObject(publishLink.getHref(), null, ...);

    // Verify state changed and links updated
    EntityModel<BlogPost> published = restTemplate.getForObject("/posts/1", ...);
    assertFalse(published.getLink("publish").isPresent());
    assertTrue(published.getLink("archive").isPresent());
}

3. Contract testing with Pact: Test that clients can handle link changes:

@Pact(consumer = "BlogClient")
public RequestResponsePact postWithPublishLink(PactDslWithProvider builder) {
    return builder
        .given("post 1 is in draft state")
        .uponReceiving("request for post 1")
        .path("/posts/1")
        .method("GET")
        .willRespondWith()
        .status(200)
        .body(new PactDslJsonBody()
            .object("_links")
                .object("publish")
                    .stringValue("href", "/posts/1/publish")
                .closeObject()
            .closeObject())
        .toPact();
}

4. Test link accessibility: Verify all links in responses are actually accessible:

@Test
public void allLinksShouldBeAccessible() {
    EntityModel<BlogPost> post = restTemplate.getForObject("/posts/1", ...);

    post.getLinks().forEach(link -> {
        ResponseEntity<String> response = restTemplate.getForEntity(
            link.getHref(), String.class);
        assertTrue(response.getStatusCode().is2xxSuccessful());
    });
}

Conclusion

HATEOAS transforms REST APIs from simple HTTP endpoints into self-documenting, evolvable systems where clients navigate through hypermedia rather than hardcoded URLs. While it adds complexity, the benefits are substantial for the right use cases:

You’ve learned:

  • ✅ What HATEOAS means and why it’s the most misunderstood REST constraint
  • ✅ How to implement HATEOAS with Spring Boot and Spring HATEOAS
  • ✅ Real-world examples with HAL+JSON format and state-driven links
  • ✅ 8 common mistakes developers make and how to avoid them
  • ✅ When to use HATEOAS and when simpler approaches suffice
  • ✅ How to test, version, and integrate HATEOAS with modern architectures

Key takeaways:

  1. HATEOAS is about discoverability: Clients learn what they can do by examining hypermedia links, not by reading documentation or hardcoding URLs.

  2. Links should be dynamic: Only include links for actions that are currently valid based on resource state. A published post shouldn’t have a “publish” link.

  3. Use standard formats: HAL+JSON provides the best balance of simplicity and tooling support. Don’t invent your own hypermedia format.

  4. Centralize link generation: Use model assemblers or resource builders to keep link logic testable and maintainable.

  5. HATEOAS isn’t always necessary: For simple CRUD APIs or internal microservices, the added complexity may not be worth it. Choose pragmatically.

Next Steps

Ready to build your own HATEOAS API? Here’s your action plan:

1. Start with a proof of concept (2-3 hours)

  • Clone the Spring Boot example from this guide
  • Implement a simple resource (User, Product, Order)
  • Add state transitions with conditional links
  • Test in Postman or curl to see HAL+JSON responses

2. Read the Spring HATEOAS documentation

3. Study hypermedia formats

4. Implement gradually

  • Start with simple self links on all resources
  • Add navigational links between related resources
  • Implement state-driven action links last
  • Measure payload size impact and optimize if needed

5. Educate your team

  • Share this guide with backend and frontend developers
  • Run a workshop on HATEOAS principles
  • Create client examples showing how to follow links
  • Document your custom link relations

Continue your REST API journey with these related topics:

Get Help and Share Your Experience

Have questions about HATEOAS? Drop a comment below and I’ll help you work through your specific scenario.

Building a HATEOAS API? I’d love to hear about your experience:

  • What challenges did you face?
  • How did your clients respond to hypermedia links?
  • What performance impact did you observe?

Found this guide helpful? Share it with your team or on social media to help other developers master HATEOAS.

Additional Resources

Official Specifications:

Tools and Libraries:

Further Reading:

Last updated: January 2025 | Reading time: 25 minutes

Ready to build truly RESTful APIs? Start with the Spring Boot example above and experiment with state-driven hypermedia links. The journey from HTTP APIs to true REST is worth it for systems that need to evolve gracefully over time.