Skip to main content

Versioning & deprecation

The contract is versioned (the reference shows the latest v1; every published version stays downloadable). Additive changes raise the minor version. Anything that would break a client needs a new major path, never a silent change to /developer/v1.

Published versions​

VersionStatus
1.0.0Published. Stays downloadable.
1.1.0Published. Latest v1. The reference and playground are generated from this document.

Download any published version from the reference or directly: openapi-1.0.0.yaml, openapi-1.0.0.json, openapi-1.1.0.yaml, openapi-1.1.0.json, openapi-latest-v1.yaml.

What changes safely​

  • Adding an operation, an optional field, or a new enum value that existing clients can ignore: minor version bump, same /developer/v1 path.
  • Removing a field, changing a field's meaning or type, narrowing an enum, or changing error shape: never done silently. These require a new major path (/developer/v2) and a deprecation notice on the old one, with an announced sunset date.
  • Scopes only narrow across a refresh; they never widen without a new player consent.

Deprecation​

A deprecated operation is marked x-release-status: deprecated in the contract before its removal date, and keeps answering correctly until that date. The changelog records every version and what changed.