API version migration moves consumers or providers from one API version to another, usually after a breaking change. The move creates costs for both sides: providers build, test, deploy, document, and support the new version while maintaining older versions; consumers update, test, and release client code, accepting delivery risk and opportunity cost. section 4.10
Migration planning accounts for several operational pressures:
- Communicate the new version and provide migration advice to consumers. section 4.10
- Update, republish, and document SDKs when they are provided. section 4.10
- Limit the number of supported old versions because maintenance competes with new features and developer-experience improvements. section 4.10
- Recognize that consumers may defer migration when the new version offers little business benefit, even when the provider considers the change inexpensive. section 4.10
Figure 4.6 Jean-Jacques Dubray’s three models of API version migration. The cost of version migration for each model is illustrated in the chart. (Source: This is adapted from JJ’s original diagram available at https://mng.bz/0GON, along with the accompanying equations.)
Compare three API consumer-migration models and the relative cost of each model, including coordinated migration in which the ecosystem moves together. section 4.10
