Skip to content

API versioning and deprecation

Current API version

The Sport Analytics API uses major-version URL prefixes.

The initial API base path is:

/api/v1

All initial handwritten application endpoints are published beneath this path.

v1 is the only supported API major version. The backend sends API-Version: v1 on every response served from /api/v1, allowing consumers to confirm the contract that handled their request.

Version selection is URI-based only. Clients must request the required major version in the path; the backend does not negotiate a resource version from Accept, query, or custom request headers. An unknown major-version path, such as /api/v2/health, returns 404 Not Found with the stable error code UNSUPPORTED_API_VERSION and directs consumers to /api/v1. A non-versioned path is not an alias for a versioned endpoint.

The OpenAPI info.version value may identify revisions to the published contract, while the URL major version represents compatibility for API consumers.

Compatible changes

Backward-compatible additions may remain within the current major API version.

Examples include:

  • adding a new optional response field;
  • adding a new optional query parameter;
  • adding a new endpoint;
  • adding a new documented error case without changing successful response meaning.

Compatible changes must still update the OpenAPI specification and relevant API documentation.

Breaking changes

A change is considered breaking when an existing compliant consumer may need to change its code to continue working.

Examples include:

  • removing or renaming a field;
  • changing a field type;
  • changing the meaning of an existing field;
  • removing an endpoint;
  • changing an existing optional field to required;
  • changing pagination or identifier semantics incompatibly.

Breaking changes must not silently replace an active contract.

A future incompatible API will use a new major version, for example:

/api/v2

Deprecation process

Before an implemented endpoint, field or API major version is retired:

  1. A replacement or migration path must be identified.
  2. The affected contract must be marked as deprecated in OpenAPI where supported.
  3. Public API documentation must identify the deprecated behaviour.
  4. Migration guidance must identify the replacement.
  5. A target retirement date or project milestone must be recorded.
  6. Consumers must be given a documented migration period.
  7. Retirement must be reviewed through the normal issue and Pull Request process.
  8. The deprecated contract may only be removed once its published retirement condition has been met.

Deprecation does not itself remove functionality.

Active lifecycle example

The former /api/v1/consumer/* cricket-resource paths are deprecated and remain fully available for existing keyed clients. Their successors are the corresponding canonical /api/v1/* paths, which accept either bounded anonymous access or a valid X-API-Key under that consumer's policy.

Each successful deprecated response includes Deprecation: ?1, the RFC 9745 Structured Field value for a deprecated resource, and an RFC 8288 Link header whose successor-version relation contains the concrete replacement URL and preserves the request query string. For example:

GET /api/v1/consumer/fixtures/100/events/export.json?overNumber=3

HTTP/1.1 200 OK
API-Version: v1
Deprecation: ?1
Link: </api/v1/fixtures/100/events/export.json?overNumber=3>; rel="successor-version"

No retirement date has been approved, so this lifecycle deliberately omits a Sunset header rather than publishing a misleading date. If retirement is scheduled, the approved HTTP-date Sunset value and migration period must be added here, in OpenAPI, and in the response middleware together.

This implements the direction accepted by ADR-016. The canonical public JSON export is no longer deprecated. All retained cricket-resource aliases below /consumer carry the same metadata and no retirement date has yet been approved.

OpenAPI status

The OpenAPI baseline may describe both implemented and agreed planned operations.

The vendor extension:

x-implementation-status

is used with the values:

implemented
planned

This prevents planned contracts from being mistaken for currently deployed functionality.

Once an operation is implemented and verified, its OpenAPI status must be updated in the same feature Pull Request.

Contract ownership

The version-controlled OpenAPI document is:

docs/api/openapi.yaml

Changes to API paths, request contracts, response contracts, authentication requirements, filtering, sorting, pagination or errors must update the OpenAPI specification in the same Pull Request.

The OpenAPI description documents the handwritten Express API. It is not generated from Supabase, PostgREST or another database API generator.

AI Declaration

The preceding document was planned, generated, reviewed and edited with the assistance of ChatGPT-Web[GPT-5.6 Sol] and Codex[GPT-5]. The issue #820 current/future deprecation boundary was documented with the assistance of Codex[GPT-5]. The issue #821 consumer-alias deprecation direction was documented with the assistance of Codex[GPT-5].