Hypermedia REST and versioning

Hypermedia REST APIs can bring some relief with this issue. In particular, Hypermedia controls provide the ability to evolve the API by dynamically defining resource links and actions. The clients of the REST service will adapt to the changes in accessing the services and considerately ignore unknown functionality.

A quite often suggested possibility is to version the API. This means introducing different operations or resources, such as /car-manufacture/v1/cars, with the version as the identifying part of the API. Versioning APIs, however, contradicts the idea of clean interfaces. In particular, since REST APIs resources represent domain entities, introducing several versions of a car doesn't make sense in business terms. The car entity is identified by its URI. Changing the URI to reflect changes in the business functionality would imply a change to the car's identity.

Sometimes several, different representations, or versions, of the same domain entities are required, for example, JSON mappings containing different sets of properties. Via HTTP interface this is achievable via content negotiation, by defining content type parameters. For example, different JSON representations for the same car can be requested via content types such as application/json;vnd.example.car+v2, if supported by the corresponding service.

Managing interfaces is a relevant topic for distributed systems. It's advisable to carefully design APIs upfront, with backwards-compatibility in mind. Extra efforts, such as additional operations that prevent an API from breaking existing functionality, should be preferred over clean interfaces that disrupt clients.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.119.136.84