API evolutions

Systems evolve over time, and the functionality that they expose changes along with these evolutions. APIs, be it in the form of a library or a RESTful API, must adapt to these changes while maintaining some form of backward compatibility.

It is therefore a good idea to consider evolutions when designing APIs. The next section describes how HATEOAS (Hypermedia As The Engine Of Application State) can be leveraged to manage evolutions.

HATEOAS

This REST principle provides a method for self-discovery for service consumers. Let's consider the following response to a RESTful endpoint:

{
  "id": 1,
  "category": "http://myservice.com/categories/33",
...
}

This response includes a hypermedia link to a related resource, so consumers do not need prior knowledge of where to fetch the resource from.

With this approach, service designers can manage evolutions by introducing new hypermedia links as changes occur, and retiring old links without requiring service...