Maintaining old API versions
The question is how to maintain old APIs without messing up the main code paths and introducing a bunch of messy if/else statements in your code.
Versioning is always a compromise between improving developer experience and the additional burden of maintaining old versions. We strive to achieve the former while minimizing the cost of the latter, and have implemented a versioning system to help us with it.
How Stripe does it:
When they need to make a backwards-incompatible change, they encapsulate it in a version change module which defines
- documentation about the change
- a transformation
- the set of API resource types that are eligible to be modified
So each new version will have a list of version change modules associated with it.
When the requested version and current version are different, Stripe first generates the response using the current version, and walks back through time to automatically apply each version change module (backwards) that it finds along the way until it reaches the requested version.
This keeps older API versions abstracted out of core code paths.
Sometimes for more complex changes, it may not modify a response but might have a side effect. These modules are assigned a has_side_effects annotation and the transformation they define is a no-op. Elsewhere in the code, there will be a check to see whether these side effect changes are active, and apply them. Changes with side effects are more complex to maintain, so they are mostly avoided.