API Deprecation Policy

Integrations are built to last, so the public API changes in a way you can plan for: a part of it is removed only after it has been deprecated, with notice.

What the policy covers

The public API is every endpoint, request parameter and response field that this user guide or the API Reference describes.

The interactive API explorer (/api-docs) lists every route the application serves, including the ones the application uses internally. A route that appears only there is not part of the public API and is not covered by this notice. When we remove one, the release notes say so and name what replaces it.

Adding something is not a breaking change: a new endpoint, a new optional parameter, a new field in a response or a new value in a list of values. Write your integration to ignore fields it does not know.

Features in Preview, and their API, can change or be withdrawn without this notice.

The notice

A deprecation is announced at least 180 days before the removal. The notice gives:

• what is deprecated;
• the retirement date, on or after which it may be removed;
• what to use instead, when something replaces it.

The deprecated part keeps working, and is supported, until the retirement date.

Where you hear about it

• Release notes. The release that announces a deprecation lists it under Deprecated, and the release that removes it under Removed: docaifabric.com/release-notes, with RSS and JSON feeds.

• What's new. A notable deprecation is also in the What's new post that follows it.

• Response headers. A deprecated endpoint's answers, including the errors it returns (an internal server error excepted), carry:

  Header	Standard	Value
  Deprecation	RFC 9745	When it was deprecated, as @ and Unix seconds: Deprecation: @1793577600
  Sunset	RFC 8594	The retirement date: Sunset: Mon, 03 May 2027 00:00:00 GMT
  Link	RFC 9745, RFC 8594	The notice (rel="deprecation") and this policy on the same deployment (rel="sunset")

  They reach your integration with every call, with no subscription needed: log them, or alert on them, to find the calls to change before the date. A deprecated field or parameter does not change its endpoint's headers: the release notes name it.

There is no separate email for API changes. How to follow the release notes and What's new, and who in your organization should (whoever owns your integrations, for these): Updates and Security Advisories.

Self-hosted deployments

A self-hosted deployment answers with the same headers. The retirement date applies to the releases published on or after it: a deployment keeps a deprecated part until it is updated to such a release.