api-versioning

API Versioning Policy

Hyrum's Law

With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended upon by somebody.

This is why backward compatibility is enforced mechanically (oasdiff), not by intention. Even "internal" details — response field ordering, timing, error message wording — become implicit contracts once consumers depend on them. Assume every observable behavior has a consumer.

Implication: changes that feel safe ("just reformatting the response", "just changing the error message") can break consumers. Run oasdiff and check usage metrics regardless.

Stability tiers

Tier	File	Behaviour
v0 / experimental	v0.yaml	Breaking changes allowed; document in info.description; skip oasdiff enforcement
v1+ / stable	v1.yaml, v2.yaml, ...	Backward compat enforced by oasdiff in CI
deprecated	any	deprecated: true on operations; Sunset header; planned removal date

Decision tree

Is the API still experimental (v0)?
├─ Yes → edit v0.yaml; breaking changes fine; no compat check required
└─ No ↓
Is the change backward compatible?
├─ Yes → bump info.version in vN.yaml; commit
└─ No → try expand-contract first
         ├─ Expand-contract works → stay on vN.yaml; bump minor
         └─ Cannot avoid breaking change → create v(N+1).yaml

Expand-contract pattern (preferred before creating a new major version)

Three phases, spread across multiple releases:

1. Expand — add the new field/endpoint alongside the old one. Minor bump. No breaking change yet. Consumers can start migrating.
2. Migrate consumers — monitor usage metrics on the old interface. Work with external consumers to switch.
3. Contract — once usage of the old interface drops to zero (or notice period elapses), deprecate and remove via the deprecation protocol below.

This avoids creating a new major version file in most cases. Start here.

When expand-contract does NOT apply:

• Narrowing request validation (tightening an existing field's allowed values) — no way to "expand" because existing valid requests become invalid
• Changing HTTP method for an existing path
• Changing a response field's type (not just name)

In these cases, your options are:

• Accept the loss: document the breaking change, bump major, migrate consumers manually
• Introduce a new endpoint with the stricter contract; deprecate the old

What oasdiff catches (breaking changes)

• Removed endpoints or HTTP methods
• Removed required response fields
• Changed field types
• New required request fields
• Narrowed enums (removing a valid value)
• Narrowed validation patterns (tightening regex, min/max length, etc.)
• Changed status codes
• Changed auth requirements

Safe changes (stay in v1, minor bump)

• New optional response fields
• New endpoints
• Relaxed enums (adding a new valid value)
• New optional query parameters
• Relaxed validation (loosening regex, increasing max length)
• New optional request fields with a server-side default

Serving versions in parallel

api/
  myservice/
    v1.yaml    # served at /v1/...
    v2.yaml    # served at /v2/...

Each version serves its own openapi.json:

• GET /v1/openapi.json → the v1 spec
• GET /v2/openapi.json → the v2 spec

The version prefix is part of the path, not a header. Generate separate clients per version.

Deprecation protocol

1. Check usage metrics — identify all affected consumers. Never deprecate blind.
2. Add deprecated: true to the affected operations in the spec.
3. Add Sunset header (RFC 8594) to responses, with the planned removal date.
4. Notice period:
   • Internal APIs: minimum 30 days
   • External/public APIs: minimum 90 days
   • Document the chosen period in info.description.
5. After removal: return 410 Gone (not 404) — consumers can distinguish deliberate removal from "resource never existed".

Agent-friendliness implications of versioning

• Parallel serving is essential: an agent that was trained on v1 must keep working during the v2 rollout. Do not remove v1 until notice period elapses.
• Deprecation announcements belong in docs/agent-integration.md — not just in the spec. Agents reading only the spec might miss the intent to deprecate.
• 410 Gone after removal is not optional — returning 404 silently lies to the agent about what was possible.

Red flags — STOP

• "The old type was wrong anyway, not really a breaking change"
• "No one is using that field"
• "We'll tell consumers on Slack" (that's not a deprecation protocol)
• "Adding a Sunset header is overkill for an internal API"
• "It's still v1, we just need to tighten validation"
• "Expand-contract is too much work for such a small change"

Anti-patterns

• Removing a field without checking usage metrics
• Changing a field's type "because the old one was wrong" — that's a breaking change regardless of the justification
• Skipping expand-contract and jumping straight to v2
• Deprecating without a notice period and a Sunset header
• Using 404 after removing an endpoint (use 410 Gone)
• Narrowing validation silently (tightening regex without a version bump) — existing valid requests start failing