Skip to main content
The Closient API changes without breaking you by surprise. Every response says which API version answered it, and an operation we plan to remove tells you so on every call, with a date and a replacement, long before it stops working.

​
The API version

Every response from an API operation carries:
It is the info.version of the OpenAPI document for that API. The paths stay under /api/v1/ for the whole of major version 1: If a client built for major version 1 sees a Closient-API-Version whose major number is higher, the server runs a newer API than the client was built for. Upgrade the client.

​
Deprecated operations

An operation we intend to remove is marked deprecated: true in the API reference, with an x-closient-deprecation object that holds the same dates and links as the headers. Every response from it, successful or not, carries three headers:
The Link entries are appended to any other links the response carries, such as pagination, so parse Link as a list per RFC 8288 rather than as a single value.

​
Our commitments

  • Notice. An operation is deprecated before it gets a Sunset date, and the Sunset header appears on every response well before that date arrives. We don’t move a published Sunset earlier.
  • A replacement. We don’t deprecate an operation without a documented way to do the same job, named in rel="successor-version" or the migration guide.
  • We watch who still calls it. Every call to a deprecated operation is recorded, and we contact organizations that still depend on it before its sunset.

​
After the sunset

From the Sunset time on, the operation answers 410 Gone without doing anything. (The one exception is an operation whose x-closient-deprecation says retiresAtSunset: false: it keeps working past its sunset, and the official clients warn at their loudest instead of failing.) The body is a standard error response whose detail names the replacement, and the deprecation headers are still attached:
Don’t retry a 410.

​
Currently deprecated

​
What the official clients do

The CLI, the Python SDK and the Terraform provider read these headers on every response:
  • Warn once per endpoint per session (CLI run, SDK client, Terraform provider process). The warning names the endpoint, the deprecation and sunset dates, the days left, the replacement and the migration guide. The CLI writes it to stderr, so stdout and --json output are unchanged. The SDK raises a ClosientDeprecationWarning. The Terraform provider adds a warning diagnostic.
  • Escalate when the sunset is 30 days away or less.
  • Fail clearly when a retired operation answers 410, with an error that names the replacement and the migration guide instead of a bare HTTP failure. A successful response past its sunset is never turned into an error.
  • Suggest an upgrade when a newer client release exists, or when Closient-API-Version reports a newer major version.
Set CLOSIENT_QUIET_DEPRECATIONS=1 to silence the warnings, for example in CI logs. It never silences the error after a sunset. The clients send no telemetry: the server already records each deprecated call.

​
Building your own client

Do what the official clients do. Check for Deprecation and Sunset in the one place every response passes through. Treat a Deprecation value you can’t parse as “deprecated, date unknown” rather than ignoring it, and treat a Sunset without Deprecation as a deprecation too. Log or alert once per endpoint, not on every call.