# Versioning and compatibility

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

Source: https://diko.app/en/api-docs/versioning

## 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](https://diko.app/en/api-docs/changelog.md).

## 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](https://diko.app/en/api-docs/changelog.md).

Every change, compatible ones included, is recorded in the [changelog](https://diko.app/en/api-docs/changelog.md).