API Versioning: The Trade-offs Nobody Mentions

The versioning decision usually gets made in one line of a planning doc: "we'll add /v2 when we need it." Eighteen months later the same team is maintaining three live contracts, a support script that maps each client to a version, and a migration that has slipped twice. It hits hardest at B2B companies with ten to fifty integration customers — big enough to have real consumers, small enough that nobody owns the API full-time.

What does a live API version actually cost you?

Every live version costs roughly the same as the first one in testing, documentation and support, minus the design work. The code is the cheap part. The expensive part is the second test matrix, the second Postman collection sitting on your client's IT team's laptop, the second set of docs, and the tribal knowledge of which customer is on which contract. In our experience, a B2B portal with around 40 endpoints and two live versions spends 15-20% more engineering time on QA and support than the same product with one. That is an illustrative range, not a benchmark, but it shows up consistently. Three versions is usually where a small team starts shipping fixes into the wrong contract.

Why is backward compatibility usually the cheaper road?

Backward compatibility is cheaper than versioning in almost every case, because an additive change costs you one field while a new version costs you an entire surface. The discipline is small enough to write on a card:

• Add fields, never remove them, until you deliberately retire a version.
• Never change a field's type or unit — including a quiet cleanup from paise to rupees.
• Ship new fields as optional, and give consumers notice before you start populating them.
• Treat enums as open sets: assume no client handles a brand-new status value on day one.

Follow those four rules and most releases never need a version bump. The rules are also testable. A schema diff in CI that fails on a removed field or a changed type catches the majority of accidental breaks before they reach anyone.

Which versioning scheme should you actually pick?

For most Indian B2B teams, URI path versioning such as /v1/orders is the right default, even though it is the least elegant option. It is visible everywhere that matters: application logs, reverse proxy routing rules, the cURL command a client's developer pastes into a support ticket, and the script your ops team uses to check who is still on the old path. Header versioning looks tidier, but it is invisible — the moment someone forgets the header they silently get v1 behaviour, and you lose an afternoon proving it. Date-based versioning, the Stripe approach, works when you have many small consumers and a mature gateway; it is harder to justify with fifteen enterprise clients and no dedicated platform team. If you run your own gateway, the routing rules deserve the same care as the code — infrastructure and server setup notes are worth a read before you commit.

What actually breaks first in practice?

The break that hurts is almost never the endpoint you deleted — it is the field you changed while keeping the same name. Take an order API where amount has always been in paise. A well-meaning cleanup ships rupees in the same field, with the same name and the same integer type. Nothing throws, nothing logs an error. The client's Tally export multiplies by 100, and the first signal is a GST filing that overstates outward supply by a figure large enough to trigger a notice. At 1,200 orders a month, that is a two-week reconciliation and a very awkward call. Timestamps fail the same way: an invoice_date that quietly switches from IST to UTC pushes a 31 March document into April and moves it across a GST period. Version numbers do not protect you from semantic drift; only explicit contracts and integration tests do.

When should you break compatibility on purpose?

Break compatibility deliberately when the old contract is producing wrong money, wrong compliance or a live security exposure — not when it is merely untidy. A field storing Aadhaar numbers or full customer identifiers that you no longer have a lawful basis to hold under the DPDP Act is a legitimate reason to remove it, and so is any field leaking another tenant's data. The technical removal is the easy half. The work is the calendar: announce a sunset date, send Deprecation and Sunset headers, log which consumers still call the old path weekly, and call your two largest clients directly. As a rule of thumb, 90 days is the floor for self-serve integrations and six months is realistic for enterprise ERP connections that get touched once a year.

Where to start

Before your next release, list every field your top five integrations actually read and treat that list as the contract — then add a schema diff to CI so a removed field fails the build rather than a customer's month-end. Decide the versioning scheme once, write it down, and resist adding a version for every change. This kind of contract review is part of how we scope platform work at Maysan Labs, and it is usually a two-hour conversation that saves a quarter of rework later.