Take your REST API to the next level with HATEOAS

A pragmatic approach to understanding HATEOAS

HATEOAS, or "Hypermedia As The Engine Of Application State", is a lot about the discoverability in a RESTful API. And it is also the part that most REST APIs misses out on. This is sad because there are a lot of benefits to reap if you take your API to the next level. Especially for the developers using your API.

Some of the benefits of using HATEOAS include simpler clients, simplified authorization control on the client side, and making your API self-documenting. If you are all new to the concept then Martin Fowler's article on the RESTful maturity model is a good start. To summarize it, the model defines four levels of maturity of the RESTfulness of an API:

1. One URI, one HTTP method
2. Multiple resources instead of a single endpoint
3. Use of HTTP verbs
4. Discoverability by using hypermedia

This model can help us understand the ideas behind REST and to fully experience the "glory of REST" the API must pass all four levels. The last level is what HATEOAS is all about and I will spend the rest of this post to discuss a somewhat pragmatic approach to how you can bring HATEOAS to your REST API.* Before we move on it is also worth mentioning another good article about the topic written by Rickard Öberg that you also might want to check out.

Combining JSON and XML in RESTful web services with Spring MVC

There are occasions when you need to support multiple representations of the same resource in a REST API. For example, a smartphone client might want the resource to be represented in JSON while your B2B partner's application that is integrating through your API wants the representation to be XML.

Willie Wheeler wrote an excellent blog post about how to support both XML and JSON from a web service endpoint using the new features of the @RequestMapping annotation in Spring 3.1. The example in the blog post, by intention, uses two different URLs for the two different representations.

However, when dealing with RESTful services the preferred approach to design your API would usually be to have a single URL for the resource regardless of what representation the requesting client is asking for. A way to solve this is to let the requesting client specify what representation it prefers via the Accept header in the HTTP request. The server will examine the request header and send back the resource in the proper representation. This can very easily be implemented by using Spring MVC and I figured I will show you how this can be accomplished with the following example.