# Versijos ir suderinamumas

> Ką žadame nekeisti /v1 ribose ir kaip pranešame apie nesuderinamus pakeitimus.

Šaltinis: https://diko.app/api-docs/versijos

## Versija kelyje

API versija yra URL kelyje: `https://api.diko.app/api/v1`. Datuotos versijos antraštės nėra. Atsakymuose nėra versijos antraštės, o versiją rodo `GET /`.

## Ką galime pridėti

Šie pakeitimai laikomi suderinamais ir gali atsirasti bet kada be įspėjimo:

- nauji endpointai;
- nauji neprivalomi užklausos parametrai;
- nauji atsakymo laukai;
- naujos enum reikšmės;
- nauji įvykių tipai ir klaidų kodai;
- ilgesni ID (iki 64 simbolių).

## Ko `/v1` ribose nedarysime

- nepašalinsime ir nepervadinsime laukų;
- nekeisime laukų tipų ar jų reikšmės prasmės;
- negriežtinsime validacijos (kas šiandien priimama, bus priimama);
- neplėsime esamų endpointų leidimų (scope) reikalavimų.

Yra viena išimtis: **saugumo pataisa, kuri susiaurina tai, ką atskleidžia atsakymas** (pavyzdžiui, paslepia lauką). Tokią pataisą užrašome [pakeitimų žurnale](https://diko.app/api-docs/pakeitimai.md).

## Kaip rašyti suderinamą klientą

Kad naujienos nesugadintų jūsų kliento:

- **ignoruokite nežinomus laukus** atsakymuose;
- **nelaikykite enum reikšmių aibės užbaigta**: nežinomą reikšmę apdorokite kaip „kita“;
- **ignoruokite nežinomus įvykių tipus** webhooks ir `GET /events`;
- **nesiremkite klaidų žinutėmis**: remkitės HTTP statusu ir `error.code`. Nežinomą kodą vertinkite pagal HTTP statusą;
- nelaikykite ID struktūros nuolatine.

## Nesuderinami pakeitimai

Nesuderinami pakeitimai bus tik naujoje versijoje `/v2`. Apie juos pranešime iš anksto:

- **bent 12 mėnesių** prieš išjungiant seną versiją;
- antraštėmis `Deprecation` (RFC 9745), `Sunset` (RFC 8594) ir `Link: <...>; rel="deprecation"` atsakymuose;
- įrašu [pakeitimų žurnale](https://diko.app/api-docs/pakeitimai.md).

Visi pakeitimai, net ir suderinami, aprašomi [pakeitimų žurnale](https://diko.app/api-docs/pakeitimai.md).