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
DeprecationandSunsetheaders, so your client can notice before the day. - Publishers are told by email, through the partner space, when a deprecation starts.