Versioning and Compatibility

Version Strategies

Perpetual stability

The general process we follow with this strategy is as follows:

1. All existing functionality is labeled “Version N” (e.g., the first version is Version 1”).

2. Any changes that are backward compatible are added directly into Version N.

3. Any new functionality that might fall afoul of our compatibility definitions is built as part of “Version N+1” (e.g., anything that is backward incompatible for Version 1 is saved for “Version 2”).

4. Once we have enough functionality to merit a new version, we release Version N+1.

5. Optionally, at some point in the future, we might deprecate Version N to avoid incurring extra maintenance costs or because no one appears to be using the version anymore.

6. At this point, we go back to step 1 and the cycle begins again.

Agile instability

• this strategy can be quite effective with active and engaged API users who are involved enough in product development to cope with frequent deprecations of previous versions in exchange for the new functionality provided.

• this strategy tends to see new versions as improvements on top of the existing versions rather than alternative views that happen to be equally good.

• Any users who require longer-term stability in exchange for having less access to new functionality over time will almost certainly find this model very difficult to use.

Semantic versioning

Making a change that would be backward incompatible? That change should be released as the next major version.

Adding some backward compatible functionality to the API? Keep the same major version but increment the minor version.

Applying a backward compatible bug fix? Keep the same major and minor version and release the patched code with an incremented patch version.

Exercises

1. Would it be considered backward compatible to change a default value of a field?

1. Imagine you have an API that caters to financial services with a large commercial bank as an important customer of the API. Many of your smaller customers want more frequent updates and new features while this large bank wants stability above all else. What can you do to balance these needs?

1. Right after launching an API, you notice a silly and embarrassing typo in a field name: port_number was accidentally called porn_number. You really want to change this quickly. What should you consider before deciding whether to make this change without changing the version number?

1. Imagine a scenario where your API, when a required field is missing, accidentally returns an empty response (200 OK in HTTP) rather than an error response (400 Bad Request), indicating that the required field is missing. Is this bug safe to fix in the same version or should it be addressed in a future version? If a future version, would this be considered a major, a minor, or a patch change according to semantic versioning?

Summary

• Versioning is a tool that allows API designers to change and evolve their APIs over time while causing as little detriment and providing as many improvements to users as possible.

• Compatibility refers to the property where code written against one version of an API will continue to function against another version.

• A new version is considered backward compatible if code written for a previous version continues to function as expected. The question that is left to interpretation is how an API designer defines user expectations.

• Often things that might seem harmless (e.g., fixing bugs) can lead to backward incompatible changes. The definition of whether a change is backward compatible is dependent on API users.

• There are several different popular versioning strategies, each with their own benefits and drawbacks. Most come down to trade-offs between granularity, simplicity, stability, new functionality, individual user happiness, and ubiquity of usability.