24 Versioning and compatibility

 

This chapter covers

  • What versioning is
  • What compatibility means
  • How to define backward compatibility
  • The trade-offs involved in choosing a versioning strategy
  • An overview of a few popular versioning strategies for web APIs

The software we build is rarely static. Instead, it tends to change and evolve frequently over time as new features are created and new functionality is added. This leads to a problem: how do we make these improvements without seriously inconveniencing users who have come to depend on things looking and acting as they did before? In this chapter, we’ll explore the most common mechanism for addressing this problem: versioning.

24.1 Motivation

Not only is software development rarely static, it is also rarely a continuous process. Even with continuous integration and deployment, we often have checkpoints or launches where some new functionality “goes live” and is visible to users, which holds especially true for web APIs. This need is exacerbated by the fact that APIs are both rigid and public, meaning changes are difficult to make safely. This leads to an obvious question: how can we make changes to a web API without causing damage to those using the API already?

24.2 Overview

24.2.1 What is compatibility?

24.2.2 Defining backward compatibility

24.3 Implementation

24.3.1 Perpetual stability

24.3.2 Agile instability

24.3.3 Semantic versioning

24.4 Trade-offs

24.4.1 Granularity vs. simplicity

24.4.2 Stability vs. new functionality

24.4.3 Happiness vs. ubiquity

24.5 Exercises

Summary