atelier/domains/api/versioning.md

API Versioning — Derived Rules

Derives from domains/api/first-principles.md P5 (Versioning) and P10 (Stability).

The Default: No Breaking Changes

• A breaking change is a new version. There is no "minor" breaking change.
• Breaking changes: removing a field, changing a field type, changing a field's semantics, changing required vs optional, changing error codes.
• Non-breaking changes: adding a field, adding an endpoint, adding an optional parameter, loosening validation.

Version Policies

URL Versioning (/v1/users)

• Simple, visible, cacheable.
• Breaking changes bump the major version: /v1 → /v2.
• Old versions are supported in parallel during the deprecation window.

Header Versioning (Accept: application/vnd.atelier.v1+json)

• Invisible in the URL; harder to test.
• Useful when the URL must stay stable (e.g., public webhooks).

Semantic Versioning (for libraries/SDKs)

• Major: breaking. Minor: additive. Patch: fix.
• Follow semver strictly. A "minor" that breaks is a lie.

Deprecation Cycle (P5 Reversibility)

1. Announce: mark the field/endpoint @deprecated with a sunset date.
2. Support: keep the old version working until the sunset date.
3. Monitor: track usage of the deprecated surface.
4. Retire: when usage drops below threshold (or sunset passes), remove.
5. Never remove without announcing. The cost of a silent break is paid by every consumer.

Sunset Headers (P9 Error Transparency)

• Deprecated endpoints return Sunset: <date> header.
• Deprecated endpoints return Deprecation: <date> header.
• A consumer who reads headers knows when to migrate.

Versioning vs Compatibility

• Versioning is the mechanism. Compatibility is the property.
• Backward compatibility: old consumers work with the new version.
• Forward compatibility: new consumers work with the old version (harder, rarer, usually not worth it).
• Aim for backward compatibility. Forward compatibility is for protocols, not APIs.

What Violates Versioning

Violation	Principle
Removing a field without deprecation	P5, P10
Changing a field's type in a "minor" release	P1, P5
No sunset header on a deprecated endpoint	P9
Two versions with divergent semantics for the same field	P1