Every SaaS product eventually faces the same uncomfortable moment: the API needs to change in a way that existing customers did not ask for. A field must be renamed, an endpoint restructured, or an old behaviour retired. Handled badly, that change breaks integrations and costs trust that took years to build. Handled well, customers barely notice. This guide sets out an API versioning strategy SaaS teams can actually follow: what counts as a breaking change, which versioning scheme to pick, how to stay backward compatible for as long as possible, and how to retire an old version without stranding anyone.
Who this is for: founders and engineering leads at SaaS companies whose customers or partners build on their API, and any team about to ship a public v1. If your API is only consumed by your own front end, you have more freedom than this guide assumes, but the discipline here will still save you pain when that API eventually goes public.
First, agree on what counts as a breaking change
Most versioning arguments are really disagreements about this list. Before you publish v1, write it down and share it with every team that touches the API. A change is breaking if an existing, correctly written client can fail, misbehave, or silently get different data because of it.
Changes that break clients
- Removing a field, endpoint, or enum value from a response
- Renaming a field, resource, or endpoint
- Changing a field’s type, for example a number becoming a string, or a single object becoming an array
- Adding a required request field or a required header
- Changing the meaning of a status code or error code, or tightening validation so previously accepted requests are rejected
- Changing default behaviour, such as pagination defaults, sort order, or timezone handling
Changes that do not break clients
- Adding a new optional request field or a new optional header
- Adding a new field to a response, provided clients ignore unknown fields, which well-written clients do
- Adding a new endpoint or a new optional query parameter
- Adding new enum values, with the caveat that strict clients may still choke, so announce these too
The practical consequence is large: most of the changes a growing SaaS needs are non-breaking if the API was designed with room to grow. Version numbers should be a last resort for genuine breaks, not a reflex every time a field is added. Teams that version on every change end up supporting five versions of the same endpoint, each with its own docs, tests, and support tickets. The rule is simple: evolve additively by default, and mint a new major version only for a change on the breaking list.
Choosing an API versioning strategy SaaS teams can live with
There are four schemes in common use, and the honest answer is that one of them is right for most SaaS products. A comparison of URL path, query parameter, and header versioning reaches the same conclusion most production teams reach: visibility beats purity.
URL path versioning: the default choice
With URL versioning the version sits in the path, as in /api/v1/invoices and /api/v2/invoices. It is explicit, trivial to route at the gateway, easy to test in a browser, and obvious in logs, analytics, and support tickets. A customer can paste a failing URL into a ticket and you immediately know which version they use. Caching works naturally because different versions are different URLs. This is the scheme used by GitHub, Twilio, and most public SaaS APIs, and it is the scheme we recommend to clients starting a public API.
Header versioning: clean URLs, hidden complexity
Header versioning keeps URLs clean and puts the version in a header, such as Accept: application/vnd.example.v2+json or a dedicated X-API-Version header. It appeals to REST purists because the resource URL does not change. In practice it is invisible: it does not show up in a pasted URL, it is easy to forget in a curl command or a test, and it is harder for less technical integrators to debug. It can work well for internal APIs with a small number of sophisticated consumers. For a public SaaS API with hundreds of integrators of varying skill, that invisibility is a support burden you will pay every week.
Query parameter and date-based versioning
Query parameter versioning, as in /api/invoices?version=2, is the easiest to implement and the easiest to regret: it pollutes the query string, breaks caching assumptions, and gets dropped when URLs are copied or logged. Date-based versioning, the Stripe style, pins each customer to a dated version and rolls changes out as a stream of dated releases rather than big-bang major versions. It is superb at Stripe’s scale, where a dedicated API platform team manages it. For a small or mid-size SaaS team it is usually too much machinery: the operational cost of per-customer version pinning and rolling migrations outweighs the benefit until you have a very large integrator base. A guide to API versioning strategies that actually work in production makes the same point from the implementer’s side: pick the scheme your team can operate for years, not the one that looks cleverest in a design doc.
Our recommendation is blunt: start with URL path versioning and major versions only, and mint a new version only for breaking changes. If you later grow into Stripe-scale complexity, date-based versioning is a migration you can make deliberately, with a platform team to run it.
Design for backward compatibility before you version
The cheapest version is the one you never have to create. Four design habits keep most changes non-breaking. First, wrap responses in a stable envelope: an object with data, and optionally meta for pagination, rather than a bare array, which cannot gain a pagination block later without breaking every client. Second, prefer additive evolution: add new fields instead of repurposing old ones, and never recycle a field name with a new meaning. Third, make new request fields optional with sensible defaults, so old clients keep working unchanged. Fourth, run contract tests in continuous integration that fail the build if a response field disappears or changes type, and keep a changelog that integrators can subscribe to.
Version your documentation alongside your API, and keep old-version docs available after a version is retired. Nothing erodes trust faster than a migration guide that 404s, or docs that describe v2 while half your customers still run v1. When you plan a new integration, our API integration guide covers the wider questions of connecting business tools reliably, which is where versioning policy meets day-to-day integration work.
From our experience: where versioning strategies actually fail
In nine-plus years of building web and API-driven systems, we have seen the same five failure modes repeat, and none of them is the versioning scheme itself. The first is over-versioning: minting v2 for a change that could have been additive, then backporting every future fix twice. The second is the undocumented v1: shipped in a hurry with no breaking-change list and no deprecation policy, so the first real break becomes a negotiation with every customer at once. The third is missing usage telemetry: nobody can say which customers still call v1, or how much traffic it carries, so deprecation decisions become guesses. Instrument version usage from day one, per API key and per endpoint. The fourth is SDK and example drift: the docs show v2 while the official SDK still defaults to v1. The fifth is supporting too many versions: two live major versions is a sensible ceiling for most SaaS teams. Three is a warning sign; if you find yourself there, the fix is a deprecation programme, not another version.
A deprecation policy customers can trust
Deprecation is where versioning strategy becomes a customer relationship. The industry consensus is a window of six to twelve months between announcing a version’s retirement and switching it off, with at least two live versions supported at any time. Shorter windows are defensible for security emergencies, and only for those: a security-driven break should be communicated as such, with a workaround, not dressed up as routine maintenance.
A deprecation programme that works looks like this. Announce with a dated sunset, not a vague promise: publish the retirement date, the successor version, and a migration guide on the same day, and put the date in the API responses themselves using the standard Deprecation and Sunset headers, plus a Link header pointing at the successor version. Notify affected customers directly: email the owners of API keys that actually call the old version at ninety, thirty, and seven days before sunset, because changelog posts are read by almost nobody. Track migration with a named owner, and set a switch-off threshold, such as old-version traffic below one percent for thirty consecutive days. After sunset, return 410 Gone rather than a generic error, with a body naming the successor version, so any client still calling the old version gets a diagnosable failure instead of a mystery.
One judgement call deserves explicit attention: never shorten a published sunset date. If migration is slower than expected, extend the date and say why. Moving a deadline earlier teaches customers that your dates cannot be trusted, and the next deprecation will be met with disbelief rather than action. The cost of running an old version for another quarter is almost always smaller than the cost of breaking a paying customer’s integration.
Frequently asked questions
Should a new SaaS API start at v1 or v0?
Start at v1. A v0 signals that breaking changes may arrive without warning, which is fine for a private beta with a handful of testers but confusing once anyone builds seriously on it. If the API is not stable enough to promise v1 behaviour, keep it in a clearly labelled beta with a small audience, and promote it to v1 when the contract is one you are willing to support.
How many API versions should we support at once?
Two major versions: the current version and the previous one, with a published sunset date for the older one. Supporting more multiplies documentation, testing, and support load for a shrinking audience. If you already support three or more, treat that as a deprecation backlog to work through, not as normal operations.
Is URL versioning or header versioning better for a public API?
URL versioning, for most public SaaS APIs. It is visible in the URL, easy to route, cache, log, and debug, and it is what most integrators expect. Header versioning suits internal APIs or cases where URL stability is a hard requirement, but its invisibility becomes a support cost with a large or varied integrator base.
When should we create a new major version instead of evolving the current one?
Only for a change on the breaking list: removing or renaming a field or endpoint, changing a type, adding a required field, or changing the meaning of a response or error. Additive changes, such as new optional fields and new endpoints, should evolve the current version without a new number.
How long should we give customers to migrate off a deprecated version?
Six to twelve months from announcement to sunset for a routine deprecation, with direct notice to affected API key owners at ninety, thirty, and seven days before the date, plus a migration guide and a named sunset date in the Deprecation and Sunset response headers. Security emergencies are the exception, and they should be labelled as such.
An API versioning strategy is ultimately a promise management system. Customers do not expect your API to stay frozen; they expect changes to arrive with warning and a path forward. Pick URL versioning, write down your breaking-change list, instrument usage from day one, and run deprecations on published dates you never move earlier. If you need help designing that policy for your product, or building the version-aware API layer behind it, our team at MTD Technologies builds custom APIs and integrations for SaaS and business software, and you can reach us through our contact page.