Versioning and deprecation policy

This page describes what you can rely on when you build against the 4league public API and the embed widget script, and how we will tell you before anything is removed.

Major version

/v1 is the current and only major version. Every response from /v1, including errors (401, 404, 405, 429, 500, 503), carries:

X-4League-Api-Version: 1

The same value is returned as apiVersion by GET /v1/ping. A new major version, if one is ever needed, would be served under a new path prefix (/v2) and run alongside /v1.

Breaking and non-breaking changes

Within /v1 we only make non-breaking changes. Anything breaking waits for a new major version or goes through the deprecation process.

Non-breaking (may happen at any time)Breaking (never without notice)
  • New fields in response objects.
  • New optional query parameters.
  • New endpoints.
  • New scope names (existing keys do not gain them automatically).
  • Removing or renaming a response field, parameter or endpoint.
  • Changing the type or meaning of an existing field.
  • Making an optional parameter required.
  • Changing the signing rules or the stable error codes.

Clients must ignore unknown fields. Do not fail on, or strictly validate against, a closed list of response properties.

Deprecation process

No endpoint is deprecated today. The Deprecation and Sunset headers described below are therefore not currently sent on any response.

When we deprecate something in /v1 we will:

  • Send a Deprecation header on the affected endpoint's responses from the announcement date.
  • Send a Sunset header with the planned removal date as an HTTP-date (for example Sunset: Wed, 11 Nov 2026 23:59:59 GMT).
  • Email the owners of every API key that called the affected endpoint.
  • Record it in the changelog below.

Minimum notice period between announcement and removal: To be announced.

Scope names

The current scopes (organizations:read, competitions:read, matches:read, standings:read, teams:read, players:read, matchStatistics:read) are provisional: a name may still change before we call the scope set stable. If one changes, we will keep the old name working as an alias and migrate existing keys to the new name, so no key loses access. Changes will be announced the same way as deprecations.

Widget script versioning

The embed widget is a script versioned independently of the API. Both URLs below serve embed.v1.js:

ChannelURLCaching
Canonical (receives fixes)https://4league.app/assets/js/widgets/embed.v1.js10 minutes
Pinned patch versionhttps://4league.ams3.cdn.digitaloceanspaces.com/embed/v1/<semver>/embed.v1.jsImmutable (max-age=31536000, immutable)
  • The canonical URL always points at the latest v1 build. Fixes and backwards-compatible additions reach your pages within about ten minutes.
  • A pinned URL never changes: a published <semver> path is never overwritten, a fix ships as a new version. Pin if you need byte-for-byte stability, and move to newer versions yourself.
  • The v1 in the file name is the widget's major version. Breaking changes would ship as embed.v2.js, and embed.v1.js would follow the deprecation process above.

Changelog

v1 launch

  • Public /v1 API released with HMAC-SHA256 request signing and organization-scoped keys.
  • Read endpoints for organizations, competitions, matches, standings, teams, players and match statistics, with a common pagination envelope and stable error codes. See the API reference.
  • X-4League-Api-Version: 1 on every response.
  • Embed widget script embed.v1.js released.
  • No deprecations.