In this article, I will explain implementing HATEOAS for a REST API with Spring Boot with an example.
What is HATEOAS?
HATEOAS stands for โHypermedia as the engine of application stateโ
It’s a complicated acronym. Let me decode it for you.
What do you visualize when you visit a web page?
The data that you would want to see. Is that all? You would also see links and buttons to see related data.
For example, if you go to a product page, you will see
- product details
- Links to Edit and Delete product details
- Links to see relevant products in that category
HATEOAS brings the exact same concepts to RESTful Web Services.
When some details of a resource are requested, you will provide the resource details as well as details of related resources and the possible actions you can perform on the resource. For example, when requesting information about a Facebook user, a REST service can return the following
- User details
- Links to get his recent comments
- Links to retrieve his friend list
- Links to get his recent posts
Sigh, a lot of things to read right? Let’s, get our hands dirty =D
Create the project
Create a new project using start.spring.io
Add basic CRUD Operation
Enhancing the resource
To implement HATEOAS, we would need to include related resources in the response. Instead of Product, I’ll use a return type of EntityModel<Product>. EntityModel is a simple class wrapping a domain object and allows adding links to it.
@GetMapping("/{id}") public EntityModel<Product> getProduct(@PathVariable long id) { Optional<Product> product = productRepository.getProductById(id); if (!product.isPresent()) throw new ProductNotFoundException("id-" + id); EntityModel<Product> resource = EntityModel.of(product.get()); WebMvcLinkBuilder linkTo = linkTo(methodOn(this.getClass()).getAllProducts()); resource.add(linkTo.withRel("all-products")); return resource; }
So what’s happening here actually?
EntityModel<Product> resource = EntityModel.of(product.get());
In the above line, we are creating a new resource. Then, adding the link to retrieve all products method to the link.
WebMvcLinkBuilder linkTo = linkTo(methodOn(this.getClass()).getAllProducts()); resource.add(linkTo.withRel("all-products"));
In the above line, we are creating a new resource. After making the changes so far, let’s start the service and see the change in action.
{“id”: 1,“name”: “Dell Precision 5550”,“currentStock”: 99,“description”: “The world’s smallest and thinnest 15 inch mobile workstation.”,“type”: “Laptop”,“dateCreated”: “2022-10-23T08:33:10.658+00:00”,“lastModified”: “2022-10-23T08:33:10.658+00:00”,“_links”: {“all-products”: {“href”: “http://localhost:3001/api/v1/product”}}}
Don’t worry, I’ve added a bootstrap class to add a few products into the DB whenever the application starts.
The above example covers important concepts in enhancing resources with HATEOAS.
However, ain’t gonna make this post longer. You have to make the important decisions:
- What are the important resources related to a specific resource?
Think of this as homework, go ahead and enhance the application with more HATEOAS links.
Oh! I forgot to give you the Github link, Here you go: https://github.com/nazrul-kabir/spring-boot-rest-service-with-hateoas Feel free to comment on the post if you have any comments.
And, don’t forget to read my other posts on Spring Boot