Versioning and compatibility

What we promise not to change inside /v1 and how we announce breaking changes.

The version is in the path

The API version is in the URL path: https://api.diko.app/api/v1. There is no dated version header. Responses carry no version header; GET / shows the version.

What we may add

These changes count as compatible and can appear at any time without notice:

new endpoints;
new optional request parameters;
new response fields;
new enum values;
new event types and error codes;
longer IDs (up to 64 characters).

What we will not do inside `/v1`

we will not remove or rename fields;
we will not change field types or what a value means;
we will not tighten validation (what is accepted today stays accepted);
we will not widen the scope requirements of existing endpoints.

There is one exception: a security fix that narrows what a response reveals (for example masking a field). We record such a fix in the changelog.

How to write a compatible client

So that additions do not break your client:

ignore unknown fields in responses;
do not assume an enum is closed: treat an unknown value as “other”;
ignore unknown event types in webhooks and GET /events;
do not look at error messages: branch on the HTTP status and error.code, and treat an unknown code by its HTTP status;
do not treat the structure of an ID as permanent.

Breaking changes

Breaking changes will come only in a new version, /v2. We will announce them in advance:

at least 12 months before the old version is switched off;
with the headers Deprecation (RFC 9745), Sunset (RFC 8594) and Link: <...>; rel="deprecation" in responses;
with an entry in the changelog.

Every change, compatible ones included, is recorded in the changelog.