IntercomProblem & solution
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.
Intercom’s engineering team faced the challenge of making backwards-incompatible changes to their APIs without breaking existing integrations, which conflicted with their principle of shipping frequently. They conducted user research to understand developer needs and identified the need for clear changelogs, advance notice, and easy testing and rollback.
Intercom implemented API versioning by introducing VersionChange objects that represent single transformations to roll back a model change to a previous version. Controllers always operate on the latest version, and transformations are applied in reverse order for older versions. Multiple VersionChanges are compiled into a Version. Developers can test with a header and upgrade via the Developer Hub.
API versioning allows Intercom to ship changes more frequently and safely without forcing all developers to upgrade immediately.
The versioning system uses VersionChange objects that transform the latest model back to previous versions, keeping controllers on the latest version.
Developers can test isolated requests using a specific header and upgrade or roll back through the Developer Hub.
They introduce version changes that transform the latest model to previous versions, allowing developers to opt-in to new versions when ready.
Yes, they can test isolated requests using a specific header to ensure compatibility before updating their app's version.
The approach was inspired by Stripe's API versioning blog post.
Summaries are generated from the original by a language model. Check the original before relying on it.
See the idea
Compare two mental models for brand: a static artifact (logos, guidelines, centralized control) and a living operating system (values, APIs, support, trust). See which choices fit your engineering team.
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.
Keep reading
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.
One useful email. Unsubscribe anytime.
