API Versioning is the thought that your REST APIs are going to change overtime. API Versioning is an essential practice when designing and building out a REST API. As updates are made to your APIs, you want to make sure you can make interface changes and progress forward without breaking current consumers use of your API.
First, and foremost, start by putting a version in your URL. This will allow you to make major version updates to your API. For example, when calling a Cloud Elements API, you use a /api-v1 or /api-v2 in the URL to indicate which major version of the API you are using. This is a common practice.
Another important type of versioning that you want your API to support is the minor-version updates. These type of changes are still changes that affect the interface, and therefore could potentially break current consumers, however they are different from the major version changes in that the URL and basic functionality of the API, is still the same. At Cloud Elements, we support minor-version changes by allowing the client to specify an HTTP header on their API calls. This header looks something like Elements-Version: 1. An example of a minor version update might be if we change the name of a JSON field in our responses. Say we have an API called GET /people that returns the following JSON payload:
We then decide, later on, that we actually want the firstN JSON field to be firstName. Obviously, this doesn’t require a major version change and a completely different URL signature, but instead we would create another API called GET /people that would require the Elements-Version: 2 HTTP header, and that API would return:
At Cloud Elements, when a new user signs up, we set their default Elements-Version header to be the latest minor-version that exists at Cloud Elements. This allows them to be locked-in to the latest we have to offer, without specifying any HTTP header on each API call. Then, they can always specify a different Elements-Version header or update their default if and when they are ready to progress forward.