coreci/atelier
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 28 Wiki Activity
Files
4e433158cd80a34dde592be3306aeb4dcc42c191
atelier/domains/api/versioning.md
T
Jon Chery 496303471d docs(milestone): complete v0.1 — initial framework 
---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.
2026-08-05 00:36:55 +00:00

2.3 KiB
Raw Blame History

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
Reference in New Issue View Git Blame Copy Permalink