API Versioning: Evolve Your Public API Without Breaking Customers

⬅️ Growth Overview

API Versioning Strategy for Your New SaaS

Goal: Ship a versioning strategy that lets you evolve your API for years — adding fields, deprecating endpoints, fixing mistakes — without breaking customer integrations. Pick a versioning scheme (URL-path / header / date-based), document the deprecation policy publicly, automate breaking-change detection in CI, and treat the API as a published contract. Avoid the failure modes where founders break customers silently with "non-breaking" changes that actually broke (every change is breaking to someone), version forever without ever deprecating (carrying 12 versions is unsustainable), or version too aggressively (v6 after 18 months looks immature).

Process: Follow this chat pattern with your AI coding tool such as Claude or v0.app. Pay attention to the notes in [brackets] and replace the bracketed text with your own content.

Timeframe: Versioning scheme + first-version cutover in 1-2 days. Breaking-change detection in CI in week 1. Public deprecation policy + customer communication in week 2. Quarterly version review baked in.

Why Most Founder API Versioning Is Broken

Three failure modes hit founders the same way:

• No versioning at all. Founder ships /api/users with no version. Six months later, a "small" change rounds the API breaks 47 customer integrations. Support inbox floods; founder rolls back; the next change is delayed for fear; the API stagnates.
• Versioning forever without deprecating. Founder ships /api/v1, then /api/v2, then /api/v3 over two years — but never deprecates v1 or v2. Now they maintain three versions of every endpoint, three sets of tests, three docs, three sets of bugs. Engineering velocity drops; new features ship to v3 only; v1 customers feel abandoned.
• Breaking changes shipped as "non-breaking." Founder thinks "renaming a field is fine, JSON is flexible." Customer code that did response.user_email now gets undefined. Customer data flows break silently; integration alerts fire days later. Trust is gone.

The version that works is structured: pick one scheme; ship one version at a time; detect breaking changes in CI; communicate deprecations early; sunset old versions on a published timeline.

This guide assumes you have already done Public API (the API surface itself), have shipped API Keys & PATs (auth for the API), and have considered Outbound Webhooks (webhooks have their own versioning concerns).

1. Pick a Versioning Scheme

Three schemes dominate. Pick one; commit; document.

Help me pick the versioning scheme for [my product].

The three schemes:

**Scheme 1: URL path versioning** (`/v1/`, `/v2/`)

Examples: GitHub (`/v3` historically), Twitter (`/2/`), Linear, most indie SaaS.

Pros:
- Most discoverable (visible in URL)
- Easy to test in browser / curl
- Simple to route in code (different controllers per version)
- Customer''s integration path is unambiguous

Cons:
- Each major version creates URL-set duplication
- Cache busting is per-version
- Less granular (every change is a major or nothing)

Use when: most indie SaaS in 2026; the default unless you have a specific reason.

**Scheme 2: Header versioning** (`Accept-Version: 2024-01-15` or `X-API-Version: 2`)

Examples: GitHub more recently (`X-GitHub-Api-Version`), Stripe (date-based via header).

Pros:
- URL stays clean
- Multiple versions can coexist on same URL
- Granular versioning possible (per-resource versions)

Cons:
- Less discoverable (need to read docs)
- Harder to test in browser
- Some clients / proxies strip non-standard headers
- Customers forget to set the header → get default version (often latest)

Use when: you want clean URLs and your developer audience is sophisticated.

**Scheme 3: Date-based versioning** (`v=2024-01-15` or via header)

Examples: Stripe (the canonical example).

Pros:
- Granular changes (each version is a small dated release)
- Customers pin to a specific date; pin upgrades happen on their schedule
- Easy to communicate ("we made changes on [date]; here''s what")

Cons:
- Many versions to maintain
- Branching logic in code can get complex
- Customers without active maintenance often pin to old date forever

Use when: you have a sophisticated customer base, frequent small changes, and engineering capacity to maintain many parallel versions.

**For most indie SaaS in 2026: URL path versioning (Scheme 1).**

URL paths are simplest, most-understood, and easiest to operate. Header / date-based schemes are powerful but add operational complexity that most teams don''t need until they have hundreds of customers integrating.

**Anti-patterns**:

- **No versioning** ("we''ll add it when we need it") — guarantees a breaking change with no version to point customers to
- **Version per release** (v1, v2, v3 every quarter) — too many versions; nobody can keep up
- **Mixed schemes** — confuses everyone

For my product:
- The scheme I''m committing to
- The reason
- The first version identifier (v1, 2024-01-15, etc.)

Output:
1. The scheme choice with reasoning
2. The first version identifier
3. The URL or header convention
4. The "default version when not specified" policy

The biggest unforced error: starting without versioning and adding it later. Once customers are integrated against an unversioned URL, adding /v1/ becomes a breaking change. Start with a version on day one of your public API; default to the right one if customers don''t specify.

2. Define What Counts as Breaking

Before shipping, agree on what''s breaking and what isn''t. The rules are clearer than founders think.

Help me classify changes as breaking or non-breaking.

The rules:

**Always BREAKING (must bump version)**:

- Removing an endpoint
- Removing a field from a response
- Renaming a field (in either request or response)
- Changing a field''s type (string → integer)
- Changing a field''s semantics (`status: "active"` now means something different)
- Adding a required field to a request
- Tightening validation (rejects previously-accepted input)
- Removing or changing an enum value in responses
- Changing an HTTP status code for a known scenario (200 → 201 or 404)
- Changing pagination behavior (offset → cursor)
- Changing default values that affect behavior

**Generally non-breaking** (still document):

- Adding a new endpoint
- Adding an optional field to a request
- Adding a new field to a response (clients should ignore unknown fields)
- Adding a new enum value (clients should handle unknown enums gracefully)
- Adding a new optional query parameter
- Loosening validation (accepts more input)
- Adding new permission scopes (existing keys still work)

**Tricky cases**:

- **Adding a field to a response**: technically non-breaking, but clients that treat responses as exact shapes (TypeScript strict, Pydantic) may break. Best practice: add fields freely; document that clients must handle unknown fields. Many SDKs do this implicitly.
- **Adding an enum value**: technically non-breaking, but clients with exhaustive switches may break. Document handling (typically: treat unknown enums as a fallback case).
- **Performance changes** (e.g., a query that was 50ms is now 500ms): not breaking by spec but operationally breaking for customers near timeouts.
- **Default value changes**: a field that defaulted to `false` now defaults to `true` — usually breaking.

**Document your policy publicly**:

- "We never break v1 customers."
- "Non-breaking changes are deployed continuously."
- "Breaking changes require version bump."
- "Customers using the SDK and following best practices (handling unknown fields gracefully) won''t break on additive changes."

For my product:
- Audit current "non-breaking" changes; were they actually non-breaking?
- The classification policy I''m publishing

Output:
1. The breaking-vs-non-breaking matrix
2. The published policy
3. The audit of recent changes

The biggest pitfall: assuming "I just added a field" is safe. A customer with strict-typed deserialization (TypeScript with strict, Pydantic, Java records) crashes on unknown fields. Document the contract explicitly: "Clients must accept unknown fields gracefully" — and assume the worst about clients that don''t.

3. Detect Breaking Changes in CI

Manual review misses things. Automate.

Set up breaking-change detection.

The pattern:

**Generate an OpenAPI spec from your code**:

If you''re using a framework that supports it:
- TypeScript: tRPC, Hono with OpenAPI plugin, NestJS with `@nestjs/swagger`
- Python: FastAPI generates OpenAPI by default
- Go: huma, kin-openapi
- Ruby: rswag

The spec lives in your repo; updates with your code.

**Diff specs in CI**:

Tools that compare two OpenAPI specs and flag breaking changes:
- **`openapi-diff`** by Tufin — fast, opinionated
- **Optic** — runs in CI; produces breaking-change reports
- **Bump.sh** — hosted spec management with diff
- **Stoplight** — comprehensive API platform

Workflow:
1. PR opens
2. CI generates new OpenAPI spec from current code
3. CI compares against the previous version''s spec (e.g., main branch)
4. CI flags any breaking changes
5. PR can''t merge with breaking changes unless explicitly tagged "BREAKING CHANGE: yes"
6. Tagged-breaking PRs require version bump

**Implementation example (GitHub Actions)**:

```yaml
- name: Generate current OpenAPI spec
  run: npm run generate:openapi -- --output current.yaml

- name: Compare to main
  run: |
    git checkout main -- openapi.yaml
    npx oasdiff breaking openapi.yaml current.yaml --fail-on ERR

What CI catches:

• Removed endpoints
• Removed fields
• Type changes
• Required → optional toggles in unsafe direction
• Enum removals
• Status code changes

What CI doesn''t catch:

• Semantic changes (field meaning changed but type same)
• Performance regressions
• Behavioral changes (a field that used to be 0-indexed is now 1-indexed)
• Default value changes

These need human review.

The "BREAKING CHANGE" PR label:

When a breaking change is intentional:

1. PR explicitly labeled breaking-change
2. PR description includes: what''s breaking, why, migration path
3. Reviewer confirms the change merits a version bump
4. Version bump happens in same PR (new endpoints under new version path)

Don''t:

• Skip CI breaking-change detection ("we''ll catch it in review")
• Allow merge of breaking changes without label + version bump
• Trust developer judgment alone (CI catches the cases humans miss)

Output:

1. The OpenAPI generation setup
2. The CI breaking-change check
3. The PR label workflow
4. The escalation process for borderline cases

The biggest single ROI improvement: **automated breaking-change detection in CI.** A team that catches breaking changes pre-merge ships fewer customer-impacting incidents than one that relies on review. The tooling exists; use it.

---

## 4. Sunset Old Versions on a Published Timeline

You can''t maintain v1 forever. Plan the sunset before you ship v2.

Design the deprecation and sunset policy.

The pattern:

Deprecation timeline (typical):

• T0: New version (v2) ships; v1 still active
• T0 + 6 months: v1 marked deprecated; new customers default to v2; old customers see deprecation notices
• T0 + 12 months: v1 sunset announced; date for full removal
• T0 + 18 months: v1 returns 410 Gone; customers must be on v2

This gives 12 months from "deprecated" to "sunset." Aggressive APIs do 6 months; conservative ones do 24+. Pick what fits your customer base.

Communication channels:

• API response headers: Deprecation: Wed, 1 Jan 2026 00:00:00 GMT
• API response headers: Sunset: Wed, 1 Jul 2026 00:00:00 GMT
• Custom header: X-Migration-Guide: https://docs.example.com/v1-to-v2
• Email customers using deprecated version (per outbound-webhooks-chat / email-deliverability-chat)
• In-product banner for active users
• Public changelog post

Tracking who''s using deprecated versions:

• Log every API request with version
• Per-customer dashboard: which versions are they using?
• Alert on customers still on v1 within X months of sunset

The migration guide:

For each deprecated version, publish:

• What changed (field renames, structural differences)
• Code samples for migration (in customer''s primary language)
• Tools / scripts to help (if applicable)
• Common gotchas

Hard deadlines vs soft:

• Hard sunset: 410 Gone after the date. Forces migration; some customers lock out.
• Soft sunset: API still works after date but with strict rate limits and warnings. Less brutal; encourages migration without breaking.

For most indie SaaS in 2026: soft-sunset for paying customers; hard-sunset for free-tier.

Escalation for laggards:

• 90 days before sunset: email
• 60 days before: email + in-product banner
• 30 days before: email + sales team outreach (for paying customers)
• 7 days before: final email
• Day 0: hard or soft sunset
• Post-sunset: documented procedure for re-enabling for stranded customers

Don''t:

• Sunset without warning (catastrophic for trust)
• Carry too many versions simultaneously (engineering overhead compounds)
• Skip the migration guide (you''ll get every customer''s questions in support)

Output:

1. The deprecation timeline
2. The communication template
3. The migration-guide structure
4. The version-usage dashboard
5. The escalation playbook for laggards

The biggest predictor of deprecation success: **early, repeated communication.** A customer who hears about sunset 30 days before is angry. A customer who hears at 12 months, 6 months, 3 months, 1 month, 1 week — each via different channels — is annoyed but not surprised. The annoyance is acceptable; the surprise is not.

---

## 5. Handle Edge Cases in Versioning

Real APIs have weird edge cases. Plan for them.

The edge case checklist.

Edge case 1: Internal vs public APIs

Your frontend calls /api/internal/... and your customers call /api/v1/.... Internal APIs change freely; public APIs are versioned strictly.

• Internal: no versioning; change at will
• Public: versioned; deprecation discipline
• Be VERY clear about the boundary (different URL prefix; different deployment if needed)
• Don''t accidentally use internal endpoints in public docs (this binds you)

Edge case 2: Webhook events versioning

Outbound webhooks (per outbound-webhooks-chat) have their own versioning concerns:

• Webhook payload versioning is separate from API versioning
• Customers'' webhook handlers may not handle new fields gracefully
• Add fields to webhooks; rarely remove; never rename in v1

Edge case 3: SDK versioning

Your TypeScript / Python / Ruby SDKs have their own versions:

• SDK v1.x targets API v1
• SDK v2.x targets API v2
• Document the SDK ↔ API mapping
• Don''t silently bump major SDK versions (semver matters)

Edge case 4: Beta / alpha endpoints

Endpoints not yet stable:

• Path: /api/v1/beta/... or /api/v1/...?beta=true
• Document explicitly: "this endpoint may change without notice"
• Don''t break v1 stability promises with beta features

Edge case 5: Tier-gated features

Endpoints only available on paid plans:

• Versioning rules apply equally
• Sunset notice goes to all users of that endpoint regardless of tier

Edge case 6: Regional / geographic variants

If you have region-specific endpoints (api.eu.example.com):

• Version each region independently or all-together (pick one; document)
• Sunset timelines align across regions

Edge case 7: Bug fixes that change behavior

A bug fix that makes the API "more correct" but breaks customers relying on the bug:

• Treat as breaking change
• New version; deprecate old
• Communicate: "we fixed a bug; the new behavior is X; the old behavior is preserved in v1 if you were depending on it"

Edge case 8: Pagination changes

Pagination is one of the most-broken-by-accident areas:

• Switching offset → cursor pagination is breaking
• Changing default page size is breaking (clients with hardcoded indices break)
• Changing the order of results without explicit order_by is borderline

Edge case 9: Authentication / authorization changes

• New auth scopes — additive (non-breaking)
• Removed scopes — breaking
• Tightening required scope on existing endpoint — breaking
• Adding rate limits — operationally breaking even if technically not

Edge case 10: Field-level deprecation within a version

Can you deprecate a single field without bumping the whole version?

• Yes, with discipline: mark deprecated in docs, return field anyway, eventually remove in next major version
• Use sparingly; better to bump versions for clean cuts

Output:

1. Edge-case handling decisions per category
2. Internal-vs-public boundary documentation
3. Beta/alpha endpoint policy

---

## 6. Use the SDK as a Versioning Buffer

A well-designed SDK absorbs many API changes invisibly. Lean on this.

Help me design SDK versioning aligned with API versioning.

The pattern:

SDK semver:

• Major version: tied to API major version
• Minor version: API additions (new endpoints, new fields)
• Patch version: bug fixes, internal SDK changes

Example:

• SDK 1.0.0 = API v1, initial release
• SDK 1.1.0 = API v1, new endpoint added
• SDK 1.1.5 = SDK bug fix
• SDK 2.0.0 = API v2 support

The SDK absorbs changes invisibly:

• Adding new fields to API responses → SDK adds typed accessors
• Renaming fields (API v1 → v2) → SDK 1.x uses old name; SDK 2.x uses new name
• New optional parameters → SDK adds them with sensible defaults
• Pagination changes → SDK abstracts them (returns iterators regardless of underlying scheme)

The SDK''s version-pinning behavior:

import { Client } from '@example/sdk'

// Defaults to the SDK''s API version
const client = new Client({ apiKey })

// Or pin explicitly
const client = new Client({ apiKey, apiVersion: 'v1' })

Critical implementation rules:

1. Publish the SDK before announcing API changes. Customers should be able to upgrade to the SDK first; then migrate at their pace.
2. Document the SDK ↔ API mapping. Each SDK version states the API versions it supports.
3. Long-term support for older SDKs. If API v1 is still supported, SDK 1.x must be maintained too.
4. SDK examples in your API docs. Customers using the SDK should rarely need raw HTTP examples.

Don''t:

• Skip SDKs ("our customers can use raw HTTP") — they''ll write bad clients; you''ll absorb the support
• Bump SDK major version without API major version (confuses everyone)
• Let SDKs lag the API (defeats the purpose)

Output:

1. The SDK ↔ API version-mapping table
2. The SDK update policy
3. The migration helpers in the SDK

The single biggest customer-trust signal: **a well-maintained SDK that absorbs API changes invisibly.** A customer using your SDK 1.x doesn''t care that you released API v2; their integration keeps working. Without the SDK, every API change is a customer code change.

---

## 7. Communicate Changes Through a Changelog

A public API changelog is non-optional. Customers monitor it.

Design the API changelog.

The pattern:

A page at /changelog (or /api/changelog) that lists every API change in reverse chronological order.

Each entry:

• Date: 2026-04-29
• Type: New / Improved / Deprecated / Removed
• Endpoint(s): which were affected
• Description: what changed
• Migration: if applicable, how to update

Example entries:

2026-04-29 — New Added POST /v1/projects/:id/archive endpoint. Archives a project without deleting it.

2026-04-15 — Deprecated The created_by field on /v1/projects is deprecated. Use created_by_user.id instead. The deprecated field will be removed in v2.

2026-04-01 — Improved The /v1/users endpoint now supports ?role= filter.

Subscription / RSS:

• RSS feed at /changelog.rss
• Email subscription for important updates
• API customers can subscribe to be notified

Versioned changelog pages:

• /changelog shows everything
• /changelog/v1 shows only v1 changes
• /changelog/v2 shows only v2 changes
• Customers focused on their version see relevant changes only

Critical implementation rules:

1. Date every entry. Not "recently"; specific date.
2. Be specific about endpoints. Customers need to find changes affecting their integration.
3. Migration guidance for deprecations. Don''t leave customers guessing.
4. Don''t hide rollbacks. If you reverted a change, say so.

Don''t:

• Bury the changelog (link from API docs prominently)
• Skip minor changes (customers want to know everything)
• Mix marketing copy with the changelog (changelog is technical)

Output:

1. The changelog page structure
2. The entry format
3. The RSS / email subscription
4. The versioned views

The biggest customer-experience lift for API customers: **a public, clear, dated changelog with RSS.** A customer who can `curl /changelog.rss` into their stack and get notified of changes builds resilient integrations. Without it, they discover changes in production.

---

## 8. Handle "We Need to Break Something Now" Carefully

Sometimes you must ship a breaking change without normal timelines. Have a playbook.

Design the emergency-breaking-change playbook.

The cases (rare but real):

• Security vulnerability — a field exposes data it shouldn''t
• Legal requirement — GDPR / regulator demands a change
• Data corruption fix — incorrect data being returned must be corrected
• Critical bug — endpoint returning wrong information

The fast-track process:

1. Validate it''s actually emergency. Most "emergencies" can wait a week. Real emergencies (security, legal) cannot.
2. Communicate FIRST. Email all customers: "We''re shipping a breaking change to X on [date] because [reason]."
3. Provide the longest reasonable warning. 24 hours minimum; 7 days where possible.
4. Ship the fix.
5. Follow up. Email impacted customers; confirm they migrated; offer support.

Mitigation patterns:

• Add the fix as a new field/endpoint; deprecate the old. Old customers continue to work for a grace period; new customers use the fixed version.
• Feature flag the fix. Customers opt in to the corrected behavior; default to old behavior temporarily.
• Bilateral migration. Reach out to top-N affected customers individually; help them migrate.

For security issues specifically:

• Don''t publicly announce the vuln until customers have migrated
• Email impacted customers with the timeline
• Issue a security advisory after the migration window
• Apply standard responsible-disclosure practice

The "we made a mistake" version:

Sometimes the breaking change is "we shouldn''t have exposed this field; we''re removing it." Same playbook applies; communicate the reason honestly.

Don''t:

• Ship breaking changes silently to "fix it"
• Skip customer communication because "it''s urgent"
• Pretend a breaking change isn''t one

Output:

1. The emergency-criteria checklist
2. The communication template
3. The escalation path within your team
4. The customer follow-up process

The biggest reputation impact: **silent breaking changes ostensibly justified by security or legal need.** Customers who get burned by a "necessary" breaking change with no warning lose trust permanently. Communicate aggressively; ship; follow up.

---

## 9. Audit Version Usage

Without metrics, you don''t know which versions to keep alive.

Design version-usage tracking.

The metrics:

Per-version metrics:

• api.requests_count — by version, by endpoint
• api.unique_consumers — by version (count distinct API keys)
• api.unique_workspaces — by version
• api.last_used_at per consumer
• api.deprecated_warning_count — how often deprecation headers fire

Per-customer metrics:

• Which versions are they using?
• How often per day?
• Have they migrated to newer versions?
• Are they on a sunset-pending version with no migration in sight?

Dashboards:

• Top customers by deprecated-version usage
• Time-series of version usage (v1 declining, v2 climbing?)
• Customers who haven''t migrated despite sunset notices

Alerts:

• New customer using deprecated version (welcome them; gently steer to current)
• Customer using v1 within 30 days of sunset and no v2 calls (escalate)
• Sudden spike in deprecated version use (might be a regression)

Sunset readiness check:

Before sunsetting v1:

• What % of total API traffic is on v1 today?
• Can we afford to lose those calls? (Probably not.)
• Have all the affected customers been contacted?
• Are any enterprise contracts blocking sunset?

Don''t:

• Sunset without checking actual usage
• Skip per-customer outreach for paying customers on deprecated versions
• Sunset on schedule when it would break enterprise contracts

Output:

1. The version-tracking metrics
2. The customer-usage dashboard
3. The sunset-readiness check
4. The escalation for laggards

The single most-useful version-usage signal: **"customers using v1 but no v2 calls in the last 30 days."** These are the customers who haven''t even started migrating. They''re your sunset risk; reach out personally.

---

## 10. Quarterly Version Review

Versioning rots. Quarterly review keeps it healthy.

Quarterly review.

Health metrics:

• Number of versions currently maintained
• Per-version traffic distribution
• Deprecation timeline adherence
• Breaking-changes-detected-in-CI count
• Breaking-changes-shipped count

Usage analysis:

• Top customers by deprecated-version usage
• Migration status per major customer
• New endpoints added; were they backward-compatible?

Engineering load:

• Hours spent per quarter maintaining old versions
• Test coverage per version
• Bug-fix backports needed?

Documentation:

• Changelog current?
• Migration guides current?
• Public deprecation calendar published?

Customer feedback:

• Support tickets about API changes
• Sales objections about API stability
• Feature requests blocked on version constraints

Output:

• Snapshot of versions and traffic
• Sunset decisions for next quarter
• 1 process improvement
• 1 communication improvement

---

## What "Done" Looks Like

A working API versioning system in 2026 has:

- A documented versioning scheme (URL path / header / date) with reasoning
- Public deprecation policy with timelines
- Breaking-change detection automated in CI
- A maintained SDK that absorbs API changes
- A public changelog with RSS
- Per-version usage dashboards
- An emergency-breaking-change playbook
- Quarterly version review baked into the team rhythm
- A documented sunset playbook with customer-escalation steps
- A handful of versions maintained simultaneously (1-3 typically; not 12)

The hidden cost in API versioning isn''t maintaining old versions — it''s **the lost momentum from never deprecating anything**. A team carrying 8 versions can''t ship product changes confidently. The discipline of "versions live X months and then sunset" creates the conditions for fast iteration. Version aggressively when needed; deprecate aggressively when planned; the API gets better while customers stay protected.

---

## See Also

- [Public API](public-api-chat.md) — the API surface itself
- [API Keys & PATs](api-keys-chat.md) — auth for the API
- [Outbound Webhooks](outbound-webhooks-chat.md) — webhooks have their own versioning
- [Audit Logs](audit-logs-chat.md) — track API usage
- [Email Deliverability](email-deliverability-chat.md) — for deprecation emails
- [Rate Limiting & Abuse](rate-limiting-abuse-chat.md) — soft-sunset uses rate limits
- [Documentation Site Builders](https://www.vibereference.com/devops-and-tools/documentation-site-builders) — where API docs and changelogs live
- [OpenAPI](https://www.vibereference.com/backend-and-data/openapi) — the spec format that drives breaking-change detection
- [Swagger](https://www.vibereference.com/backend-and-data/swagger) — alternative spec
- [API Testing Tools](https://www.vibereference.com/devops-and-tools/api-testing-tools) — Bruno / Postman for testing per-version
- [CI/CD Providers](https://www.vibereference.com/devops-and-tools/cicd-providers) — where CI checks run

[⬅️ Growth Overview](README.md)