API Stability Policy
This document describes how the Aetherin contract (openapi/openapi.yaml) evolves and how breaking changes are introduced.
Stability tiers
- Stable (`/v1`): endpoints and fields documented in the current spec. Once
shipped in a non-pre-release version, they are supported for the lifetime of the major version.
- Beta / RC: pre-release versions (
-rc,-beta) may change without
notice; consumers should pin to a released version.
- Deprecated: marked with
deprecated: truein the spec and kept functional
for at least one minor release (or 90 days, whichever is longer) before removal.
What counts as a breaking change
- Removing or renaming an endpoint, field, or enum value.
- Changing a field's type or required/optional status in an incompatible way.
- Altering response status codes or error semantics.
- Changing authentication or security requirements.
Breaking change process
- Open a proposal issue describing the change, motivation, and migration path.
- Add the new behavior under a new major version prefix (e.g.
/v2) while
keeping /v1 intact.
- Mark affected
/v1operations or fields asdeprecated: truewith a
removal target.
- Bump
VERSIONmajor component (e.g.1.x->2.0.0) and update
info.version in openapi/openapi.yaml and package.json.
- Regenerate clients (
npm run generate:ts,oapi-codegen) and update
downstream repos; CI fails on drift.
- Document the migration in
CHANGELOG.mdunder a new major heading. - After the deprecation window, remove the deprecated
/v1surface in the
next major release.
Non-breaking changes
Non-breaking additions (new endpoints, optional fields, new enum values) bump the minor or patch component of VERSION and do not require a new prefix.
Versioning of the contract
See openapi/README.md for the mechanical versioning rules and generation commands.