Versioning and deprecation

The API is versioned by date, not by address. Additions ship any day. A change that could break your code ships when it is needed, and the changelog announces it the day it ships, marked Breaking. There is no fixed notice period.

If this policy changes, the changelog says so.

One API, versioned by date

There is one version of the API at a time, on one address. The /v1 in the paths is part of the address. It does not change when the API changes.
Every change is listed in the changelog under the day it shipped. The API's version is the date of the newest entry, today 2026-11-04. The OpenAPI document gives it as info.version.
Test keys and live keys call the same API. A test key sees every change at the same time as a live key.

Changes that can ship any day

These do not break code that follows the rules below. They ship without notice and are listed in the changelog:

new endpoints;
new optional parameters, and new optional fields in a request body;
new fields in answers, in problem bodies and in webhook bodies;
new values in a field documented as open;
new problem codes;
new response headers, and new webhook events (a receiver gets only the events it asked for).

A fix that makes the API do what these pages already say also ships any day, and is listed.

What your code must do

Ignore fields you do not know, in answers, problem bodies and webhook bodies.
Accept a value you do not know in a field documented as open.
Handle a problem code you do not know by its HTTP status, and its retryable. Branch on code, never on detail.
Do not rely on the order of fields in an object.
If your code checks answers against the OpenAPI document, for example with generated types, regenerate them when the changelog lists a new field.

Breaking changes

A breaking change is one that can stop working code: removing or renaming an endpoint, a field or a parameter; changing a field's type or meaning; making an optional parameter required. There is no fixed notice period for one. It goes like this:

It ships when it is needed, on any day.
The changelog lists it under the day it ships, marked Breaking. The entry says what changed and what to do instead.
Where it is cheap to keep the old behaviour for a while, it is kept for an overlap. The changelog lists the affected operations as Deprecated on the day the change ships, with the day the old behaviour stops (the sunset date). There is no promised minimum: the overlap can be short, and there may be none.
During an overlap the operations are marked deprecated: true in the OpenAPI document, with the dates in x-compudime-deprecated-since and x-compudime-sunset. Their reference pages say so too. They keep working as before, and every answer from them carries three headers:
- Deprecation (RFC 9745): when the deprecation was announced, as @ and Unix seconds.
- Sunset (RFC 8594): when the operation may stop working, as an HTTP date.
- Link with rel="deprecation": the changelog entry that announced it.
On or after the sunset date the old behaviour stops, and the changelog lists that under the day, marked Breaking.

For example, an endpoint deprecated on 2027-01-04 with its sunset on 2027-04-05 answers:

Deprecation: @1799020800
Sunset: Mon, 05 Apr 2027 00:00:00 GMT
Link: <https://api.compudime.com/docs/changelog#2027-01-04>; rel="deprecation"; type="text/html"

Log these headers when you see them. They are the same for test keys and live keys.

A field can also be deprecated in name only, like upc on products, which is still served beside its new name unitsPerCase. The schema marks it deprecated. It keeps working until the changelog lists its removal.

Deprecated today

No endpoint is deprecated.

How you hear about changes

The changelog, newest first.
info.version in the OpenAPI document: compare it with the one you read last.
The Deprecation and Sunset headers on the answers you already get.
A breaking change can ship any day: when a call that worked starts to fail, look at the changelog for that day first.
Questions: support@compudime.com.