Versioning and deprecation

Versions

• The major version is in the URL: /v1. A new major (/v2) is introduced only for changes that can't be made compatibly, and /v1 keeps running alongside it.
• Within /v1, every response carries API-Version (for example 1.1.0), the release that served it. The OpenAPI document's info.version matches.

What we may change without notice

These are backwards-compatible. Write clients that tolerate them:

• Adding endpoints, optional request fields, response fields, enum values or headers
• Adding error code values
• Changing the order of fields in a response, or error message wording
• Tightening validation of input that was already documented as invalid

What needs a deprecation

Removing or renaming an endpoint, field or enum value, making an optional input required, or changing the type or meaning of a field. These follow the deprecation process and are never done in place.

Deprecation process

1. The endpoint is marked deprecated in the OpenAPI document (deprecated: true, x-sunset) and in the reference.

2. Its responses gain headers:

   Deprecation: @1790812800
   Sunset: Thu, 01 Apr 2027 00:00:00 GMT
   Link: <https://docs.salesos.org/developers/versioning>; rel="deprecation", <https://api.salesos.org/v1/api-keys/{id}/rotate>; rel="successor-version"

   Deprecation (RFC 9745) is the date it was deprecated, Sunset (RFC 8594) is the earliest removal date, and Link rel="successor-version" points at the replacement.

3. At least 6 months pass between deprecation and sunset (12 months for core CRM resources).

4. Organizations still calling it are contacted before the sunset date.

5. After the sunset date the endpoint may return 410 Gone.

Deprecated endpoints you still call

SalesOS records every call to a deprecated endpoint, per API key (or per signed-in user for browser sessions). Settings → API Keys lists the ones your organization called in the last 30 days, with the key, the call count and the sunset date. The same data is at GET /v1/api-keys/deprecated-usage.

Currently deprecated