How to make your REST APIs backward-compatible


Representational State Transfer, commonly known as REST, is an architectural style—a set of constraints used to implement stateless services that run on HTTP. A RESTful API is one that conforms to the REST constraints. You can build RESTful APIs using many different programming languages.

Maintaining backward compatibility between different releases of your API is of utmost importance in ensuring that your API will remain compatible with all of the clients that consume it. This article presents a discussion of how you can maintain backward compatibility in your RESTful APIs.

API compatibility example

Assume that you have an API in production that is being consumed by different clients. Now if you want to add more functionality to the API, you should ensure that the clients that use the old API will be able to use either the new API or the old one. In other words, you should ensure that the existing functionality of the API will remain intact while the new functionality is added.

An API is backward compatible if a client (a program written to consume the API) that can work with one version of the API can work the same way with future versions of the API. In other words, an API is backward compatible between releases if the clients should are able to work with a new version of the API seamlessly.

Let’s understand this with an example. Assume that you have an API method named GetOrders as shown in the code snippet below.