API Versioning for Early SaaS Without Painting Yourself Into a Corner

API versioning is one of those decisions early SaaS teams make once and then live with for years. Get it right and you can ship breaking changes without breaking customers. Get it wrong and you either ship no breaking changes ever, or you break customers a lot.

This post is the working version — the versioning options, what actually happens when you pick each one, and what small SaaS teams should pick at v1 to buy themselves flexibility without over-engineering.

Why versioning matters even for a new API

Your API is a contract. The moment customers write code against it, changing that contract has a cost. Renaming a field, removing an endpoint, changing a response shape — each one can break integrations.

Versioning gives you a controlled way to make those changes. Without a versioning story, you're either frozen on your original decisions or you're breaking customers whenever you improve the API.

The main options

URL versioning

The path contains the version: /v1/customers, /v2/customers. Simple, visible, easy to explain. Every mainstream API most developers have integrated with uses this. Stripe uses date-based versioning for behavior changes on top, but the URL is still /v1.

Pros: obvious in logs, cache-friendly, easy to route different versions to different backend code. Cons: bumping to v2 is a big deal — you're announcing an entire new API. Most teams that do URL versioning stay on v1 for years.

Header versioning

The version is in a header: Accept: application/vnd.myapi.v2+json or X-API-Version: 2. Cleaner URLs. More flexibility for granular versioning.

Pros: separates version from URL structure, more expressive. Cons: harder to test in a browser, easier to forget, less obvious in logs.

Date-based versioning

The client sends a version pinned to a date: X-API-Version: 2027-03-01. Every breaking change gets a new date. Clients pin the date when they integrate and only upgrade when they're ready.

Pros: fine-grained control, matches how you actually make changes. Cons: needs machinery on the server to serve multiple versions. Stripe and a few other large APIs run this.

No versioning

Sometimes a legitimate choice for internal APIs or very early public APIs. You just ship changes and communicate them. Fast to move. Bad for customers past a certain size.

What we recommend at v1

URL versioning with /v1, plus a documented deprecation policy. That's it.

You're not big enough to need date-based versioning yet. You will be someday. In the meantime, adding /v1 to your URLs costs nothing and gives you an escape hatch. Every breaking change forces the "do we need v2?" question, which usually reveals that a small non-breaking addition works instead.

Deprecation is the actual policy

Versioning is not the point. Deprecation is. Versioning gives you the ability to run two versions simultaneously; deprecation is how you get customers off the old one.

A working policy: breaking changes get 6 months' notice. During that window, both versions run. After that, the old version returns a specific status code or gets removed. Announcement channels are documented in advance — changelog, email, in-response headers if you want to be helpful.

What counts as a breaking change

Sharper than most teams realize:

Removing a field. Breaking. Even fields marked optional in your docs are relied on somewhere.

Renaming a field. Breaking.

Changing a field type. Breaking. Even int-to-string.

Making an optional field required. Breaking for the customer who wasn't sending it.

Changing the default value of a field. Breaking.

Adding a new required field on requests. Breaking.

Adding a new field on responses. Not breaking, if clients are correctly ignoring unknown fields (which they usually are).

Adding a new endpoint. Not breaking.

Adding new enum values. Technically breaking. Callers who match exhaustively will break. In practice, most SDKs handle it.

Where teams get versioning wrong

Bumping to v2 for the wrong reason

A new v2 API is a huge event for customers. They have to migrate. Most changes don't warrant it. If you find yourself considering v2 for the third time in a year, you probably need date-based versioning, not another URL.

No deprecation policy

Versioning without a plan to sunset old versions leaves you supporting three versions of your API forever. Write the policy before shipping v1.

Silent breaking changes on v1

The worst outcome. You said v1 was stable, then you shipped a breaking change on it. Customers stop trusting your changelog. Recover from this with a public apology and a stricter internal policy going forward.

Versioning without a spec

OpenAPI or an equivalent spec is the contract. Without one, "what changed" is a matter of memory. With one, you can diff between versions and see exactly. Ship a spec at v1.

Client libraries

Once you have SDKs (Python, JavaScript, whatever), the SDK abstracts most versioning pain. Customers depend on the SDK version, and the SDK maps to an API version internally. New API version, new SDK major version.

This gives you room to move faster on the wire protocol while keeping developer experience stable. The trade-off is that you're now on the hook for SDK maintenance.

Backwards-compatible changes are your friend

Most improvements can be shipped backwards-compatibly with a little care. Add a new field instead of changing an old one. Add a new endpoint instead of changing the shape of an existing one. Accept both old and new inputs during a transition.

The teams that stay on v1 for five years do this systematically. It's not accident. It's design.

Mistakes teams make

Overengineering versioning at v1. Date-based versioning with a full deprecation harness before you have 10 customers is theatrical. URL versioning is fine.

Under-engineering the deprecation policy. Versioning without deprecation is a broken system. Write the policy early.

Not documenting the spec. Customers who can't diff your API can't know what changed. Publish the spec.

Skipping communication channels. Even a well-versioned API needs a changelog, an email list, and a public status page. That's the versioning UI.

Trade-offs

URL versioning is simple but coarse. Date-based versioning is fine-grained but complex. Header versioning is flexible but easy to overlook. No versioning is fast but expensive later.

At small scale, favor simple. Move to complex when you can articulate why the simple version stopped working.

Common misconceptions

"Versioning means never breaking." It means breaking on purpose, with notice, in a way customers can manage.

"Semantic versioning solves it." SemVer is for libraries. APIs need a versioning scheme that's controlled by the server, not the client.

"We'll add versioning later." Later is much harder. Prefix the URL now.

Frequently asked questions

Should I start with /v1 in my URLs?

Yes. It costs nothing and buys you optionality forever.

URL versioning or header versioning?

URL for public APIs. Simpler, more visible, easier to debug.

Do I need a spec?

Yes. OpenAPI or equivalent. Ship it at v1.

What's a reasonable deprecation window?

Six months for public APIs. Longer for enterprise contracts.

When should I go to v2?

When you have a broadly better shape for the API and are ready to migrate customers. Not for small breaking changes — those go through deprecation on v1.

Conclusion

API versioning for early SaaS doesn't need to be fancy. URL versioning with a documented deprecation policy handles most SaaS APIs for years. Ship the spec. Communicate changes. Keep breaking changes rare and announced.

The teams that get burned by versioning are the ones that either over-engineered it early (nobody uses the fancy machinery) or under-engineered it (they end up trapped in decisions they made in week one).

If your API is starting to attract enterprise customers and you're wondering whether your versioning story will hold up, our SaaS & web app team has walked teams through this exact transition many times.