Skip to main content

Versioning and deprecation

In this page you will learn which changes to expect inside version 1, and what the platform promises before it removes anything.

The contract​

Version 1 of the App API and of the webhooks is a frozen contract: the OpenAPI document of /api/app/v1 and one JSON Schema per webhook topic. The platform checks every change of its code against them, and refuses a change that breaks them. You can download the OpenAPI document and generate your client from it.

What can change inside version 1​

Only additions:

  • a new operation, a new optional parameter, a new field in an answer or in a webhook's data, a new value in a documented list of values;
  • a new webhook topic, a new scope, a new extension slot.

So your code must ignore a field it does not know, accept a value it does not know, and not rely on the order of fields.

What does not change​

Within version 1, nothing is removed, renamed or made stricter: no operation, field or topic disappears, no type becomes narrower, no optional input becomes required. A change of that kind is a version 2, on a new path (/api/app/v2) with its own envelope version.

Deprecation​

  • A version 2 does not remove version 1. Version 1 is kept for 12 months after version 2 ships.
  • A deprecated operation answers Deprecation and Sunset headers, so your client can notice before the day.
  • Publishers are told by email, through the partner space, when a deprecation starts.