Spring HATEOAS (Hypermedia as the Engine of Application State) is a powerful library that simplifies the implementation of hypermedia-driven REST APIs. One of its key features is support for HAL-FORMS — an extension of HAL that allows expressing UI templates within hypermedia responses.
However, developers often run into template rendering errors when using HAL-FORMS with Spring HATEOAS. These can range from missing templates to serialization failures, and they typically arise due to misconfiguration or misuse of the API.
In this article, we’ll explore:
- What causes HAL-FORMS rendering errors
- How to fix them
- Best practices for working with templates
- Practical examples
✅ What Are HAL-FORMS Templates?
HAL-FORMS templates enable clients to understand how to interact with resources without external documentation. For example, a GET request to a resource could return not only the current state, but also a form that tells the client how to create or update the resource.
{
"_links": {
"self": { "href": "/employees/1" }
},
"name": "John Doe",
"role": "Developer",
"_templates": {
"default": {
"method": "PUT",
"properties": [
{ "name": "name", "required": true },
{ "name": "role", "required": true }
]
}
}
}
❌ Common HAL-FORMS Template Rendering Errors
1. _templates Section Missing
Symptom: You see the HAL _links, but the _templates section is missing.
Cause: You didn’t register or configure the template properly in the controller.
Fix: Use RepresentationModel and add templates using TemplateAffordance.
@GetMapping("/employees/{id}")
public EntityModel<Employee> getEmployee(@PathVariable Long id) {
Employee employee = employeeRepository.findById(id).orElseThrow();
Link selfLink = linkTo(methodOn(EmployeeController.class).getEmployee(id)).withSelfRel();
Affordance updateAffordance = afford(methodOn(EmployeeController.class).updateEmployee(id, null));
return EntityModel.of(employee, selfLink.andAffordance(updateAffordance));
}
2. Serialization Error: No serializer found for class Template
Symptom: Internal server error with serialization failure.
Cause: Jackson doesn’t know how to serialize the HAL-FORMS-specific Template object.
Fix: Ensure you’re using the correct media type (application/prs.hal-forms+json) and that the Jackson HAL-FORMS module is on the classpath.
implementation 'org.springframework.boot:spring-boot-starter-hateoas'
Ensure configuration:
@Configuration
public class HateoasConfig {
@Bean
public ObjectMapper halFormsObjectMapper() {
return new ObjectMapper()
.registerModule(new Jackson2HalFormsModule())
.setSerializationInclusion(JsonInclude.Include.NON_NULL);
}
}
3. Media Type Not Respected
Symptom: The client receives standard HAL JSON, but no form templates.
Cause: Spring HATEOAS needs to know that the client wants HAL-FORMS.
Fix: Set the correct Accept header in the request:
Accept: application/prs.hal-forms+json
Also ensure your controller returns RepresentationModel, EntityModel, or CollectionModel.
✅ Example: Creating a HAL-FORMS Template for a Resource
Suppose you have an Employee entity. Let’s build a GET endpoint that returns a form for updating the employee.
@PutMapping("/employees/{id}")
public ResponseEntity<?> updateEmployee(@PathVariable Long id, @RequestBody Employee newEmployee) {
// logic...
return ResponseEntity.noContent().build();
}
And now, expose a GET endpoint with HAL-FORMS affordance:
@GetMapping("/employees/{id}")
public EntityModel<Employee> getEmployee(@PathVariable Long id) {
Employee employee = employeeRepository.findById(id).orElseThrow();
Link selfLink = linkTo(methodOn(EmployeeController.class).getEmployee(id)).withSelfRel();
Affordance updateAffordance = afford(methodOn(EmployeeController.class).updateEmployee(id, null));
return EntityModel.of(employee, selfLink.andAffordance(updateAffordance));
}
When the client requests with Accept: application/prs.hal-forms+json, the response now includes the template.
🧠 Best Practices for Using HAL-FORMS in Spring HATEOAS
- Always provide affordance methods for POST/PUT/PATCH endpoints.
- Use
afford()on links to generate templates automatically. - Don’t forget the correct media type in the request.
- Ensure Jackson modules for HAL-FORMS are configured.
- Avoid returning raw POJOs — always use
RepresentationModelor its subclasses.
🛠 Troubleshooting Checklist
| Problem | Likely Cause | Suggested Fix |
|---|---|---|
_templates missing | Affordance not added | Use .andAffordance(...) on Link |
| Serialization error | Missing Jackson module | Register Jackson2HalFormsModule |
| No HAL-FORMS response | Incorrect Accept header | Use application/prs.hal-forms+json |
| Incomplete form fields | Missing method parameters or model hints | Ensure method signatures and annotations are present |
📦 Conclusion
HAL-FORMS offers a powerful way to make your REST API self-descriptive and client-friendly, but Spring HATEOAS requires proper setup to generate and render templates correctly. Most rendering errors are tied to affordance misconfigurations, media type issues, or missing Jackson modules. By following the guidelines and examples above, you can fix these issues and provide a richer hypermedia experience for clients.
