Skip to main content
Every operation in the OpenAPI document states its stability in x-stability-level, and every change to it is in the changelog. Today every operation is beta, and none is deprecated.

​
Stability levels

  • beta: the operation may change, or be removed, in place. Every change is a changelog entry that says what a client must do. New operations start here.
  • stable: the operation only gains. It may gain an optional request field, a response field, a value of an extensible enum (x-extensible-enum), a new error code or a new operation beside it. Anything else is a breaking change and ships as a new operation (see below). It is removed only after a deprecation and its sunset.
Read the document’s x-extensible-enum values as the ones known today: handle a value you do not know, and ignore a response field you do not know. An operation is promoted from beta to stable on its own, when all of these hold:
  1. It has been live for at least 30 days, and its contract has not changed in the last 14.
  2. It declares its real error responses and examples.
  3. Its main path is covered by an end-to-end test of the API key surface.
  4. Its growing vocabularies are extensible enums or open objects.
  5. It is documented here: its endpoint page, and a guide when it is part of a multi-step flow.
A promotion is a changelog entry. A stable operation is never demoted to beta.

​
Deprecation

An operation on its way out is marked in the OpenAPI document:
  • deprecated: true;
  • x-deprecated-since: the day it was deprecated, YYYY-MM-DD;
  • x-sunset: the first day it may be gone, once its removal is scheduled;
  • x-replacement: the operationId of the operation to move to, when there is one.
Every response of a deprecated operation, errors included, carries the same in its headers:
  • Deprecation (RFC 9745) is the day it was deprecated, in seconds since 1970-01-01 UTC.
  • Sunset (RFC 8594) is the first day it may be gone. It is absent while no removal is scheduled.
  • The deprecation link points to this changelog, which names the deprecation and what to use instead. On the API host it follows the Link values every response carries.
A stable operation is deprecated with a sunset at least 183 days after the deprecation reaches production. A beta operation may be deprecated before its sunset is set. After the sunset, the operation is removed and its path answers 404. To notice a deprecation early, log the Deprecation header when a response carries it, and move to the replacement before the sunset. The TypeScript SDK warns once per process when it sends a deprecated operation, and its types mark the operation @deprecated.

​
Breaking changes and /v2

A breaking change to a stable operation ships as a new operation with its own operationId, under /v2: for example companiesV2.list at GET /v2/companies. The /v1 operation stays as it is, is deprecated with x-replacement naming the new one, and is removed only after its sunset. Both are in the document at the same time, so you move one call at a time.

​
SDK versions

@enrik/sdk stays at 0.x while the API is in beta. It becomes 1.0.0 when the v1 operations become stable.