Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
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 | |