Versioning

The platform API is versioned in its path: every route is under /api/platform/v1. This page says what may change within a version, what never will, and how you hear of a change before it reaches you.

What a version promises

Within v1, a change never breaks a client written against the API reference and the OpenAPI document. These changes may come at any time, without notice, and your client must take them in its stride:

  • New routes, and new optional query parameters or body fields on existing ones.
  • New fields in an answer. Read the fields you know and ignore the rest; never refuse an answer for having more than you expected.
  • New error codes, on a route that could already refuse. Branch on the codes you handle, and treat any other by its HTTP status.
  • New values in a field documented as open-ended, such as a session's status or a definition's kind. Treat an unknown value as you would a missing one.
  • Reworded messages. A refusal's message is for people; branch on error.
  • Different cursors. A cursor is opaque, and what it holds may change at any time.
  • Higher limits: larger bodies, longer strings, more seats. A lower limit is a breaking change.

These are breaking, and never happen within v1:

  • Removing or renaming a route, a field, a query parameter or an error code.
  • Changing what a field, an error code or a status means, or a field's type.
  • Making an optional field or parameter required, or refusing a request that was accepted.
  • Changing a route's credential to one a caller may not hold.

Deprecation

When something in v1 is to be removed, it is first deprecated, and keeps working:

  1. The Changelog says what is deprecated, what replaces it, and the earliest date it can be removed: never sooner than six months after the notice.
  2. A deprecated route's answers carry a Deprecation header (RFC 9745) with the moment it was deprecated, and a Sunset header (RFC 8594) with the date it may be removed, so your client can log a warning without anybody reading the changelog. The OpenAPI document marks it deprecated.

The notice is never shorter than six months, except where keeping something would put players or their data at risk. In that case the changelog says so.

A new version

A change that cannot be made within v1 comes in v2, at its own path, alongside v1. Both versions run together for at least twelve months from the day v2 is released, and the changelog says how to move from one to the other.

What is not covered

  • Routes and fields not in the API reference or the OpenAPI document. Anything you find that is not documented may change or go without notice.
  • The console, which is a web application, not an API.
  • Rate limits and quotas, which are your org's plan's and change with it; see the console's Usage page.
  • Security fixes. A change needed to keep players or studios safe is made at once, and posted in the changelog.