Rest api versioning strategy. Versioning a REST API - version identifier in the URI or version media types?

Rest api versioning strategy

Versioning Strategy

Rest api versioning strategy. Every which way you turn there are different philosophical takes on “the right way” and lots of backwards and forwards on REST, what is RESTful, what is not and if it even matters. Let's talk about API changes, the impact on versioning, why there are so many diverging ideas on how it should be done and.

Rest api versioning strategy

Internally, we update minor and patch versions whenever we add functionality and backward-compatible updates. When we release a new major version of the xMatters REST API, clients can choose to either continue using an existing major version or migrate to the new one.

REST is by far the most prominent architectural style used today to expose services to third parties over the internet. The reason REST has been so successful is that it mimics how the web works:. Clients may not want to update their applications when the API changes, so a versioning strategy becomes crucial.

This strategy is used by xMatters as well as other companies such as Facebook, Twitter, Airbnb, and others. Because cache keys in this situation URIs are changed by version, clients can easily cache resources. The internal version of the API looks as follows: Internally, a new major version implies creating a new API and the version number is used to route to the correct host.

Minor and Patch versions: These are transparent to the client and used internally for backward-compatible updates. They are usually communicated in change logs to inform clients about a new functionality or a bug fix.

This solution has a pretty big footprint in the code base as introducing breaking changes implies branching the entire API. This is a straightforward way of versioning an API from an implementation point of view. It is also easy to default to the latest version if a query parameter is not specified. The main drawback comparing to the URI versioning is the difficulty of routing.

Query parameters are in fact more difficult to use for routing requests to the proper API version. The last strategy we are addressing is versioning through content negotiation. This approach allows us to version a single resource representation instead of versioning the entire API which gives us a more granular control over versioning.

Summary Versioning is a crucial part of API design. Content negotiation is a more granular approach because it versions resource representations instead of versioning the entire API, but it also comes with a high implementation cost for both clients and developers.

More often than not, content negotiation needs to be implemented from scratch as there are few libraries that offer that out of the box. Read the white paper. Do we need to make packging folder as per the major version? Another question is, How the version the schema if Api change require change in database tables. One thing that is not very often documented is how to manage the code and all the versions that are supported by the API. My implementation of 3rd approach for spring-webmvc: Our dedicated community site is the best place to get help on all xMatters products.

Our team of expert support staff and users inside our community can help you get the right answer. Facebook Twitter Linkedin Feed. The reason REST has been so successful is that it mimics how the web works.

Versioning is a crucial part of API design that gives developers the freedom to refactor their code and work on better representations for the resources of their API. You may also be interested in. Policy Privacy Policy Contact Sales.


648 649 650 651 652