Versijos ir suderinamumas

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

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.

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.

Visi pakeitimai, net ir suderinami, aprašomi pakeitimų žurnale.