Handling API changes
An integration is not finished at go-live; it is finished when it is decommissioned. This is how the platform changes underneath it, and what your side has to do about it.
One version, and it changes additively
There is one current version, /v1, and every path lives under it. Inside a
version, changes are additive:
| Additive — happens without notice | Breaking — never happens inside a version |
|---|---|
| A new resource appears | A field is removed |
| A new optional field appears in a response | A field changes type |
| A new optional parameter is accepted | A required parameter is added |
| A new value appears in an enumerated field | A resource or endpoint is removed |
| A new event topic appears | The meaning of an existing field changes |
That contract is only worth anything if your side holds up its half, which is one rule:
The same applies to enumerated values. A new order status, list kind or event topic appearing is additive; code that switches exhaustively and throws on the default case is code that will throw.
Where changes are announced
Four channels fire together, so there is no single point of failure in finding out:
| Channel | What it carries | Who should watch it |
|---|---|---|
| The changelog | Every change, grouped as added / changed / deprecated / fixed / removed. Available by email and RSS | The integration owner, and each integrator |
| The Developer Portal at revenexx.dev | Migration guides, published before a breaking change ships | Whoever will do the work |
| Response headers | A signal on the calls themselves once something is deprecated | Your monitoring |
| Direct email | Sent to registered integration contacts | Whoever you registered |
The last row is worth acting on today: make sure the registered contact for each integration is a team address, not a developer who left in 2026. That is the message that reaches you personally when something is about to break.
The deprecation lifecycle
Nothing disappears without warning. When a version or an endpoint is retired, it moves through four stages:
| Stage | What it means | Duration | What you do |
|---|---|---|---|
| Current | Fully supported | — | Nothing |
| Deprecated | Still works. A replacement exists and the migration guide is published | At least four weeks | Plan and schedule the work |
| Sunset | Still works, but you are past the intended cut-over | A short final window | Migrate now |
| Removed | Gone. Calls fail | — | Too late |
While something is deprecated, responses to it carry a signal — a deprecation marker and the date it is scheduled to disappear. Two things to do with that:
Log it. An integration that quietly keeps working against a deprecated endpoint for three months is one that will stop working without anybody having noticed the warnings.
Alert on it. Treat the first appearance of a deprecation signal as an event worth waking somebody up to read — not to fix that night, but to schedule. Four weeks is enough time if you start on day one and not enough if you start in week three.
Event topics version differently
Worth knowing because it catches people out: a breaking change to an event
payload does not change the existing topic. It ships as a new topic with a
version suffix — order.created becomes order.created.v2 — and both run in
parallel for a while.
That means your receiver keeps working, unchanged, on the old topic. It also
means you have to actively subscribe to the new one to get the new shape, and
that nobody will do it for you. When a .v2 topic appears in Events › Event
Catalog, that is your notice.
Testing the next version
The point of a sandbox is that this is not frightening.
- Read the migration guide and mark which of your integrations are actually affected. Usually it is one, not all of them.
- Point the sandbox integration at the new behaviour and run your fixture tests — the same idempotency, replay and timeout tests you ran at go-live.
- Run the real volume once. Migration changes sometimes change performance as well as shape.
- Deploy to production during the deprecation window, not the sunset one.
- Watch the logs for a week before considering it done.
If the sandbox has drifted from production, refresh it before you start — a migration tested against a stale tenant is a migration you have not tested. See Set up a sandbox.
A change register worth keeping
One table, one page, reviewed quarterly. It answers the only question that matters when a deprecation notice arrives: does this affect us, and who does the work?
| Column | Example |
|---|---|
| Integration | ERP order sync |
| Owner (a team, not a person) | IT Systems |
| Resources and topics used | /orders, orders/{id}/acknowledge, order.created |
| Key | erp-order-sync-prod |
| Last reviewed | 2027-03 |
| Notes | Also consumes the nightly price export |
Fifteen minutes to build, and it turns every future deprecation notice from an investigation into a lookup.
What to check, quarterly
- Every integration in the register still exists, and everything that exists is in the register.
- The registered contact for each is a team address that someone reads.
- No integration is calling something marked deprecated.
- Somebody has read the changelog since the last review.
Next
- Monitor your integrations — where the deprecation signal shows up.
- Test an integration end to end — the tests to re-run on every migration.