Versioning & deprecation

This policy governs the stability of the Public API (/api/public/v1/*, REST and GraphQL). It does not apply to the internal routes the first-party web app uses, which carry no stability guarantee.

Version scheme

The Public API is versioned in the URL path:

/api/public/v1/...
/api/public/v2/...   (a future major version)

• The path segment (v1, v2, …) is the major version. A new major version ships under a new path; the old path keeps serving its own contract unchanged.
• The OpenAPI document's info.version is a semantic version whose MAJOR equals the path version (v1 → 1.x.x). MINOR increments on backward-compatible additions; PATCH on documentation fixes with no behavioral change.
• GraphQL shares the same surface and version.

Non-breaking (within a major version)

Clients must tolerate these without breaking:

• New endpoints, queries, mutations, and resources. (A new resource also adds its :read / :write scope tokens. Because scopes carry no wildcards, existing keys do not auto-gain access; they keep working and are re-issued to opt in.)
• New optional request fields, query parameters, or GraphQL arguments.
• New fields on response objects; REST clients must ignore unknown fields.
• New enum values: clients must tolerate values they do not recognize.
• New error codes in the catalogue.
• Relaxed validation, and performance or wording changes.

Breaking (requires a new major version)

Never made in place; shipped under a new version path:

• Removing or renaming an endpoint, field, query parameter, enum value, or error code.
• Changing a field's type, or making an optional field required.
• Changing the shape of the pagination envelope, the cursor format, or the error envelope.
• Tightening validation so previously-accepted input is rejected.
• Changing authentication, scoping, or default behavior in an observable way.

Deprecation signalling

When something is slated for removal, we signal it well in advance:

• Deprecation header (RFC 8594) on affected responses.
• Sunset header (RFC 8594) once a removal date is scheduled.
• The OpenAPI document marks deprecated operations with deprecated: true; GraphQL uses the @deprecated directive.

Support window

After a new major version reaches stable release, the previous major is supported for at least 6 months before its sunset date:

1. v(N+1) ships and is documented as stable.
2. vN responses begin carrying Deprecation (and, once scheduled, Sunset) headers.
3. vN keeps serving its unchanged contract for ≥ 6 months from the v(N+1) stable date.
4. On or after the Sunset date, vN may be removed.

The window is a minimum; a longer one may be granted and announced.