Jon Chery
54 lines
2.3 KiB
Markdown
54 lines
2.3 KiB
Markdown
# 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 | |