Back to all articles
APIs as a ProductPart 05
API versioningAPI productsDeprecationPartner integrations

APIs as a Product, Part 5: Upgrade on Your Schedule

Janahan Thavendran5 min read

TL;DR

  • One core serves internal teams and partners, so version it once and promise that consumers upgrade on their own schedule while old versions retire on a published timeline.
  • The core ships without waiting; consumers update their integration code, cached data and error handling, and version lag runs from days for internal teams to months for mobile apps.
  • Deprecate by tracking who still calls the old version, by consumer and traffic, and switch off only near zero traffic or on an agreed date.
In this article

APIs as a Product, Part 5 of 10 · Versioning without breaking 50 partners.

Months after we announced the switch-off, one partner's old app was still sending a third of their traffic.

Their release shipped once a month and went through app-store review. From our side the deprecation date had passed. From theirs, nothing had changed.

That was when versioning stopped being a technical rule and became a promise to people whose release cycle I didn't control.

One core, versioned once

That partner wasn't the only consumer on its own clock. The same order API served our own ordering app, our loyalty service and every partner on the open API. A change to the core was a change for all of them at once.

So we made one promise to everyone who called it: consumers upgrade when they choose, we retire old versions on a published timeline, and nobody is surprised.

In practice, a new version shipped alongside the old one, never as a forced cutover. The old version kept running while each consumer moved at its own pace, and nobody's pace matched anybody else's. An internal team might ship every week. A partner might ship once a month, behind app-store review. If either had to wait for the other, the core would have become the thing that slowed the whole business down.

What actually has to upgrade

It helped to be precise about what upgrading meant. The core didn't wait for anyone: new versions of the loyalty, menu, transaction, catalog and payment APIs shipped when the business needed them. What had to move was on the consumer's side: their integration code, any data they had cached, and the way they handled errors. The old version stayed up while they did it.

Each door moved on its own trigger. An internal team moved in its own sprint, against its own roadmap. A partner moved in its own release, sometimes tied to a commercial agreement. A developer on the open API moved whenever they chose, with nobody to coordinate.

The gap between a new version shipping and a consumer moving to it is version lag, and it depends on who the consumer is. For our own teams it was usually days or weeks. For a partner with a web integration, weeks. For a partner with a mobile app, months: app-store review first, then customers who don't update straight away. The lag isn't laziness. It's built into how each consumer ships.

What breaking really means

Most teams define a breaking change as something that changes the contract: removing a field, renaming it, changing its type, making an optional field required. That list is right, but it's incomplete. With 50+ partners, a change breaks things if any reasonable partner could have built on the old behaviour.

So our list grew. Tightening validation was breaking, because requests that used to pass would now fail. Changing the order of webhook events was breaking, because some partners processed them in sequence. New values in a closed list were risky, so we told partners up front that lists could grow and that unknown values should be handled, not rejected.

Loyalty showed why this matters to people who never see an API. Some partner apps cached loyalty balances. For them, a change to how points were returned wouldn't throw an error anywhere. It would show a customer the wrong number of points, and the customer would call the merchant, not us.

You can't retire what you can't see

Announcing a switch-off date, it turned out, didn't retire anything. The partner still on the old version wasn't ignoring us. Its customers were on the old app, and it could only move them as fast as its release cycle allowed.

What worked was knowing, for every consumer, internal team or partner, who was still calling the old version and how much traffic it carried. Not whether they had said they would upgrade, but whether they were still calling the old endpoint. With that, deprecation became a series of conversations rather than an announcement. We published the date and the support window early, flagged the old version in responses, reached out directly to the teams and partners still using it, and only switched it off once the traffic was close to zero or the partner had agreed a date.

This is also where product and engineering have to agree on cost. Every old version you keep alive is code someone maintains, tests and monitors. Every version you switch off too early is a partner whose customers can't order. There is no free option, only a trade-off you should make on purpose.

You don't shorten version lag by forcing anyone. You shorten it by making the new version easy to adopt, the old one safe to stay on, and the retirement date predictable. Pressure can move a partner's date in a meeting. It can't move their app-store review.

A version is a promise to people whose code you will never read, inside the company and outside it. The hardest part of keeping it isn't the version number. It's knowing who is still standing on the old floor before you take it away.


Related reading: keeping partner contracts stable through an acquisition, including deprecation as a long programme, is covered in The Shared Platform, Part 2.