Spring HATEOAS — Hypermedia Driven RESTful APIs

November 3, 2022

Spring HATEOAS — Hypermedia Driven RESTful APIs

Servers should tell clients what can be the next step or avoid them to define static end-point rules on client side in RESTful API world. Spring HATEOAS is doing just the exact case to serve clients what the next steps are during run-time by with providing hypermedia driven RESTful APIs.

What is Spring HATEOAS?

Before giving a code example, let’s examine what is Spring HATEOAS and what are the benefits using it.

HATEOAS stands for Hypermedia as the Engine of Application State and it is giving an overview to the client about the next steps with the URI of the referenced objects dynamically and their state transitions.

For more information, pls check Spring HATEOAS page.

Feature of HATEOAS

As mentioned in Spring HATEOAS page, there are there main features provided by Spring HATEOAS;

  • Model classes for link, resource representation models,
  • Link builder API to create links pointing to Spring MVC controller methods
  • Support for hypermedia formats like HAL

Usage of HATEOAS

For example, client can get all objects in an entity as referenced and then client needs to get a specific item with details. At that point, HATEOAS comes in help by providing the GET API URI to the client. So, client does not need to store any static information about the next steps in the process and gets whatever it needs in the next state within that state transition.

restful-api-response-with-hateoas

As seen in the above example, when the client gets a list of lecture object data as reference and there are href to retrieve the detailed information for each lecture object. So, the client only needs to call that URI in the href to get details for the specific object data.

getting-the-next-step-with-hateoas

Spring HATEOAS is very useful especially in large scaled projects using microservices. With the new RESTful architecture, managing the APIs on clients are getting easier as HATEOAS provides the required data dynamically during runtime.


Code Example for Spring HATEOAS

So, let’s continue with a coding example to see how to use Spring HATEOAS. Before starting, let me make a kind reminder that you can again reach the code base from my-hateoas-example repository in my GitHub account.

Also, in this example, you can find the usage of MapStruct, Lombok and MongoDB integrations in Spring Boot.

Two main entities will be created during this code example, Student & Lecture. And, also two more controllers in order to manage this MongoDB documents, StudentController & LectureController. I will not give code snippets (gists) for each classes. You can check the code base in my account for the overall view.

First of all, let’s add the HATEOAS dependency in our pom.xml.

Embedded content: https://gist.github.com/evrentan/cbc989450dca0cd52dcc27abffad4688#file-hateoas_dependency-pom-xml


Then, let’s create our entities, StudentEntity & LectureEntity.

Embedded content: https://gist.github.com/evrentan/897d8e865868d2493aa33d1706823e1d#file-studententity-java


Now, it is time to create our DTOs. The important point is here to extend our DTO with RepresentationModel class within Spring HATEOAS library. This class provides the functionality for adding hrefs and other HATEOAS components to our classes.

Embedded content: https://gist.github.com/evrentan/3109045c5e78e39ab36cc30da2df1afe#file-student-java


Our entities & DTOs are created, so it is time to create our mappers to make them available in our service implementations. Just one hint about StudentMapper is that it also uses LectureMapper as our StudentEntity & Student classes have lecture related object lists in them.

Embedded content: https://gist.github.com/evrentan/1b84cd0310401242a29c9cdb8c9d7c1b#file-studentmapper-java


Our backbone for the example code base is ready. Now, let’s create our repositories, interfaces.

Embedded content: https://gist.github.com/evrentan/a4a0cf56d7916e606a434290d2b6ea7d#file-studentrepository-java

Embedded content: https://gist.github.com/evrentan/5b5c090a81b3feb854a27c0d8338b931#file-istudentservice-java


So, it is time to use HATEOAS functionalities in our service implementation classes. For the whole code block for service implementation of interface classes, you can check my-hateoas-example repo in my GitHub account. I will only give code snippets related to HATEOAS usage within this article.

Embedded content: https://gist.github.com/evrentan/60ee08d4d058b6772b1773e35184d83b#file-studentserviceimpl-java

With the help of WebMvcLinkBuilder class provided by Spring HATEOAS library, building URIs is really easy.

  • linkTo method → finds the controller class & its root mapping, which are “/student” for StudentController & “/lecture” for LectureController in our example.
  • slash method → add the variable to the link, which are studentId & lectureId in our example
  • withSelfRel method → defines that the href is a self link.
  • withRel method → relation type for the href can be defined with this method if required like “lectureRel”.

Finally, we are at the last step, creating our controllers for student & lecture.

Embedded content: https://gist.github.com/evrentan/01bc8d6e98ebdcaf94145324339676ea#file-studentcontroller-java

So, our controller methods produces HAL (Hypertext Application Language) JSON formats in order to define hypermedia links/URIs to clients.

Spring HATEOAS also provides a CollectionModel class for your return types in order define them in collections supported with HAL format.


In a nutshell, Spring HATEOAS provides very beneficial dynamic functionalities to be consumed in our RESTful APIs especially to make life easier on client sides. With HATEOAS, next steps in our microservices are more concrete and dynamic.

Please, refer to my GitHub page for the complete Spring HATEOAS example repository, my-hateoas-example repo.

Share: