ADR 0004: API Versioning Policy

Ratification

Adopted before ADR 0018. There was no separate ratification process. Git history for this file on main is the record.

• Discussion Issue: not recorded (before ADR 0018)
• Merge PR: see git history for this file
• Accepted: as merged to main

Context

Why this matters: A public API is a promise. If you rename a field or change an error meaning without warning, clients break — often only in production. The major version in the URL (/api/v1) is a clear signal: everything under that prefix follows one set of compatibility rules.

Without written rules, teams ship “small” changes that are actually breaking. Clear rules for additive vs breaking changes and a deprecation period keep trust with integrators.

Decision

We use path-based major versions. Within one major, we prefer additive, backward-compatible changes:

1. Major API version is encoded in URL prefix (current: /api/v1).
2. v1 accepts only backward-compatible changes.
3. Breaking changes require a new major version (for example /api/v2).
4. Error contract semantics for existing code/key pairs are immutable.
5. Deprecated contract elements must keep a migration window of at least 90 days (or two release cycles, whichever is longer).

Compatibility Rules

Breaking changes (forbidden inside same major)

• Endpoint removal or rename.
• Field removal, rename, type change, or semantic change.
• Existing optional field becoming required.
• Enum value removal or semantic repurposing.
• Repurposing existing business/validation error code and key.

Non-breaking changes (allowed inside same major)

• Adding new endpoints.
• Adding optional fields.
• Adding new error codes with new keys.
• Documentation/example improvements without runtime behavior change.

Deprecation Policy

When deprecating behavior, document migration path and timeline in:

• README.md
• docs/internal/system-design.html
• ADR notes (if policy-level)

If deprecation headers are enabled, use:

• Deprecation: true
• Sunset: <date>
• Link: <migration-guide>; rel="deprecation"

Implementation Guidance

For contract-related changes:

1. Update request/response schemas.
2. Update router responses and OpenAPI examples.
3. Add compatibility and regression tests.
4. Run make release-check and make docs-fix.
5. Record policy-level decisions in ADR.

Consequences

Positive

• Predictable API evolution for clients.
• Lower risk of accidental contract breaks.
• Clear migration expectations.

Trade-offs

• Additional governance overhead for API changes.
• Longer lifecycle for deprecated behavior support.

Page history