A version change module is a separate, declarative component that transforms a resource or response from the latest API representation into the version requested by a consumer. section 4.10
A compatible version-migration design applies the modules as follows:
- Keep the core API service on its latest version while maintaining older-version transformations separately. section 4.10
- Build the proposed response using the latest code, then inspect the requested API version. section 4.10
- Apply transformation functions backward, in order, from the current version until the desired version is reached. section 4.10
- Document each transformation so the declarations can help generate API changelog notifications. section 4.10
Compatible API versioning
Stripe uses version change modules so one current API service can handle backward-incompatible requests from consumers using older API versions. 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 compatible migration with alternative version-migration models and their relative costs as the number of API versions grows. section 4.10
