Loading…
Topic
1 post about API Versioning. Every summary links to the original.
See the idea
An app store is a distribution surface, a versioned contract, and a health loop between a platform and its developers. Here is how those parts fit together and why each one fails loudly if ignored.
API versioning as an architecture: requests enter through a version header, pass through a chain of reversible version changes, and reach controllers that only ever see the latest model.
The Good Stuff
Paid picks we use ourselves. Links carry a referral code — a subscription through one earns us a commission at no extra cost to you.
Newest first
Intercom introduced API versioning for their REST and Messenger Framework APIs, using their open-source Requisite library, enabling safe, frequent updates without breaking existing integrations. Previously, API changes required advance notice and coordinated migrations, which was unreliable and hindered iteration, so they conducted user research to identify friction points. The versioning system uses ‘version changes’ — single transformations that roll back a model change to a previous version, such as renaming user_id to customer_id, allowing controllers to always operate on the latest version and chain multiple changes. Developers can test isolated requests using a specific header and upgrade through the Developer Hub, with the ability to roll back immediately if something goes wrong. This design, inspired by Stripe’s approach, allows Intercom to ship changes more frequently and safely across REST API, Messenger Framework, and webhooks.
The best engineering reads, once a week.
