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.