Introduction to HATEOAS With Spring Boot Data Rest

HATEOAS (Hypermedia as the Engine of Application State) specifies that the REST API’s
should provide enough information to the client to interact with the server.
This is different from the SOA (Service-Oriented Architecture) where a client
and a server interact through a fixed contract. We’ll look more into HATEOAS in a while.

Spring Data Rest is built on top of Spring Data, Spring Web MVC & Spring Hateos.
It analyzes all the domain models and exposes Hypermedia Driven REST endpoints
for them automatically. In the meanwhile, all the features of Spring Data Repositories
like sorting, pagination etc. are available in these endpoints.

We’ll see with the help of a very simple example how to implement this.

Dependencies

We’ll use Gradle to build our project.

We’ll use H2 to run our project. The same concept can be applied for different databases
like MongoDB, MySQL etc. The full list of supported databases is given
here.

Spring Data Rest

In this example, we’ll use JPA to create cities and countries.

Let’s have a look at our Country class.

Let’s have a look at our City class.

As we are using JPA in our project, we are creating an association between a City and a Country.
Many Cities can be associated with a Country.

Let’s create the repositories for them.

This will create a repository for Country and also expose the REST endpoints (GET, POST, PUT, DELETE, PATCH) for the same.
As JPARepository extends PagingAndSortingRepository, paging & sorting functionality will be automatically added for the GET endpoint.
By default, the path is derived from the uncapitalized, pluralized, simple class name of the domain class being managed.
In our case, the path will be countries.

We have customized the path to metropolises.

HATEOAS

Let’s check the APIs after we run our project.

curl 'http://localhost:8080'

We get some information about the available APIs. We can further explore about the metadata by
hitting the profile API. You can read more about the metadata
here.

Let’s add a few Countries.

Let’s fetch a paginated result of Countries with the results sorted by Country name, the
page size 2 and the 1st page.

curl 'http://localhost:8080/countries/?sort=name,asc&page=1&size=2'

Apart from the expected countries, we also get the links to different pages and
further information that might help in handling pagination better.

The links to the first, previous, self, next and last pages can directly be used.