HATEOAS stands for Hypertext As The Engine of Application State. The theory is that by embedding enough information in our API responses it will be easier to use the API without needing to consult documentation.

HATOEAS is important for providing a uniform interface – one of the key REST API Constraints. Think of HATEOAS providing a map to the available endpoints around each request.

The client should be able to interact with the REST API using the links sent back by it. There shouldn’t need to be a ton of hardcoded file paths in the system and documentation shouldn’t be necessary when doing the implementation for file paths.

For example, if I structure my API to have departments/:departmentId/employees if I do a request to a specific department endpoint I should get a response back like:

{
	"id": 5,
	"department": "engineering",
	"links": [{
            "href": "5/employees",
            "rel": "employees",
            "type" : "GET"
        }, {
            "href": "5/expenses",
            "rel": "expenses",
            "type" : "GET"
        }
    ]
}

HATEOAS can be a great way of us telling us what is allowed or not allowed for a certain resource. For example, maybe I want to be able to add employees or remove employees from my department. The UI could detect whether that is allowed based on the links.

The biggest benefit of HATEOAS is that it allows the server to potentially make URI changes without breaking the clients because they should be using the dynamic links that are provided.

HATEOAS has a number of different potential forms RFC 5988 which provides a target URI, Link relation type, and an attributes for target.

JSON Hypermedia API Language (HAL) is another potential option which includes a target URI, link relation and a type.

I prefer to provide a bit similar variant that makes life a bit easier:

{
	"id": 5,
	"department": "engineering",
	"links": [{
            "href": "https://api.example.com/departments/5/employees",
			"documentation-link": "https://documentation.example.com/get-department-employees"
            "rel": "employees",
            "type" : "GET"
        }, {
            "href": "https://api.example.com/departments/5/expenses",
			"documentation-link": "https://documentation.example.com/get-department-expenses"
            "rel": "expenses",
            "type" : "GET"
        }
    ]
}

I prefer this approach because it gives everything that somebody would need to build an integration into my api.

---

Also published on Medium.