Versioning and deprecation

Applies to the partner API under /public/v1. The machine-readable contract is openapi.json (OpenAPI 3.1), also served live at GET /public/v1/openapi.json.

Versions

• The major version is in the URL: /public/v1/.... There are no version headers or query parameters.
• A major version is a stable contract. Within it we only make additive changes:
  • new operations, resources or optional query parameters;
  • new optional request fields;
  • new response fields (clients must ignore fields they don't know);
  • new values in an enum that is documented as open (e.g. source), new error codes, new webhook event types;
  • relaxing a validation rule.
• Breaking changes ship only in a new major version (/public/v2). A breaking change is anything that can make a correct v1 client fail: removing or renaming an operation, field or parameter; making an optional input required; changing a field's type, format or meaning; tightening validation; changing an error status or code; changing authentication or the scopes an operation needs.
• When v2 ships, v1 keeps running unchanged for at least six months (see below) and both are documented side by side.
• info.version in the OpenAPI document is the semver of the v1 contract: minor for additive changes, patch for documentation fixes.

Deprecation

Deprecating an operation (or all of v1) gives at least six months' notice between the announcement and the sunset date. During that window the operation keeps working and every response carries:

The OpenAPI document marks the operation deprecated: true and states the sunset date. Partners are also told directly by the partnerships team when a deprecation is announced. After the sunset date the operation answers 410 Gone with the error envelope (code: "GONE") and the same headers.