API Versioning

Introduction

Good API designs try to maintain stability at the API specification level to minimize the need for multiple versions of the same API. Even well-constructed APIs need changes due to the evolution of requirements and/or technology. A slight alteration can either break the functionality for those who utilize the API in their applications or lead to unwanted side effects in their functionality.

API versioning is the practice of developers improving their APIs while still leaving the prior iterations functional for clients. It gives users the freedom to upgrade to new versions at their own pace, rather than forcing the update onto them, which might break their existing application. For example, popular APIs, such as the Graph API for Facebook, might be in use for billions of users, and implementing an update to the API might make the application lose its functionality.

Expecting every single user to update to the newer client version is not a reasonable expectation. So how do we manage a new version on the server-side when many clients might still be using an older version? There may come the point where a developer aims to depreciate older versions of an API, but with versioning, consumers are given time and the option to update their applications to the version they desire.

However, not all changes warrant an entirely new version to be implemented. Let's take a look at what situations and alterations merit an upgrade. First, we’ll evaluate the key principles of versioning and whether our APIs need it or not. Then, we'll highlight how to implement and ...