Skip to main content

API versioning

Public API endpoints include a version in the URL:

/v1

For example:

GET /v1/clubs

Compatible changes​

The following changes can generally be introduced without a new major API version:

  • New optional response fields
  • New endpoints
  • New optional query parameters
  • New enum values where the schema permits extensible codes
  • Additional error details
  • Documentation corrections

Clients should ignore response fields they do not recognize unless their application explicitly needs them.

Avoid exhaustive enum handling that crashes when a new canonical value appears. Provide a safe fallback such as unknown in the user interface.

Breaking changes​

Changes that can require a new API version include:

  • Removing or renaming fields
  • Changing a field's type or meaning
  • Making an optional request field required
  • Changing authentication semantics
  • Restructuring successful responses incompatibly

Breaking changes will be introduced under a new versioned path rather than silently changing the established contract.

Deprecation​

When an API version or endpoint is scheduled for retirement, integrations should receive a migration period and clear replacement guidance. Applications should monitor release notes and deprecation notices.

Do not construct version URLs dynamically based on the newest version. Configure the version intentionally so upgrades can be tested before production deployment.