- Improve the REST API without breaking old integrations. - Common wisdom is semantic versioning - /api/v1, /api/v2 - Incentivises big-bang changes. - Splits user base between versions. - We believe infrastructure should be boring. - Enter Rolling Versions.
What are Rolling Versions? Rolling Versions is an API versioning technique that ensures backward-compatibility by applying request and response transformation to each user request using change objects.
A quick example In this example, we describe an API used to retrieve a list of user objects, with the date versioning scheme. Versions - Initial Version - 2023-04-01 - 2023-05-01
Limitations httptest.ResponseRecorder - Designed for the test environment. - Enabled Quick Prototyping. - Backwards Compatible with Handlers. - Works with early versions of Go. http.ResponseController - Designed for regular production code. - Might not be Backwards Compatible with your Handlers. - Works with only Go 1.20+
Parting thoughts - Some changes to the API are much more complex than response transformations. See Changes with side effects in the Stripe article. - Handling arbitrary data migrations, e.g. Webhook payloads.