Verzije i kompatibilnost

API ima jednu glavnu verziju, /v1, i ona samo raste. Integracija napisana danas nastavlja raditi kako stižu nove mogućnosti: ništa na što se oslanja ne preimenuje se, ne uklanja i ne dobiva novo značenje.

Broj verzije

API ima broj verzije kao što je 1.62.0. Mijenja se sa svakim izdanjem:

• broj sporedne verzije kad se nešto doda: operacija, polje, događaj;
• broj zakrpe kad se ispravi opis ili tekst poruke, a ništa se drugo ne mijenja.

Verziju koju adresa poslužuje možete pročitati u bilo kojem trenutku:

I GET /v1/health ima version, ali to je verzija izdanja Surse koje poslužuje adresu, a ne verzija API-ja.

Sporednu verziju ne birate: svaki zahtjev poslužuje trenutačna verzija. Zahvaljujući pravilima u nastavku, to je sigurno.

Što se može promijeniti u /v1

Ove promjene mogu doći u bilo kojoj sporednoj verziji. Napišite integraciju tako da je one ne naruše:

• Nove operacije.
• Novi neobavezni parametri i polja zahtjeva. Zahtjevi bez njih ponašaju se kao i prije.
• Nova polja u odgovorima, objektima i događajima.
• Nove vrijednosti nabrajanja u odgovorima, kao što je novi status kartice ili nova vrsta događaja.
• Novi kodovi pogrešaka i nova zaglavlja odgovora.
• Ograničenja koja postaju blaža: veća najveća duljina, širi raspon.
• Preformulirani tekstovi message u pogreškama i preformulirani opisi.

Što vaš kod mora podnositi

• Zanemarujte polja koja ne poznajete. Nemojte prekidati rad kad odgovor ima više polja nego što očekujete i ne koristite stroge sheme koje ih odbijaju.
• Prihvaćajte vrijednosti nabrajanja koje ne poznajete. Svako nabrajanje u odgovoru može rasti. Nepoznatu vrijednost tretirajte kao „ostalo”, a ne kao pogrešku.
• Preskačite vrste događaja koje ne poznajete, i u webhookovima i u tokovima.
• Nepoznate kodove pogrešaka obrađujte prema njihovu HTTP statusu: v. Pogreške.
• Ne oslanjajte se na redoslijed polja u JSON objektima ni na točan tekst poruka.

Što se u /v1 nikada ne mijenja

• Putanja, parametar, polje ili vrijednost nabrajanja nikada se ne preimenuju i ne uklanjaju.
• Tip polja nikada se ne mijenja i polje nikada ne dobiva novo značenje, primjerice nove jedinice.
• Zahtjev koji se danas prihvaća neće se kasnije odbiti.
• Statusni kod uspješnog odgovora ostaje isti.
• Kodovi pogrešaka zadržavaju svoje značenje, a polje detail u odgovorima s pogreškom zadržava svoj oblik.
• Vrste događaja nikada se ne preimenuju i ne uklanjaju, a njihov data samo dobiva nova polja.

Nekompatibilne promjene

Ako ikada bude potrebna nekompatibilna promjena, ona se izdaje kao nova glavna verzija, kao što je /v2, uz /v1. /v1 nastavlja raditi nepromijenjen, a dvije verzije rade usporedno.

Kad se neka ruta treba ukinuti:

1. U specifikaciji se označava kao deprecated i navodi se u dnevniku promjena s datumom kad će biti isključena.
2. Njezini odgovori nose zaglavlja Deprecation: true i Sunset: <date>.
3. Nastavlja raditi najmanje 180 dana nakon najave. Organizacije čiji je API ključevi koriste obavještavaju se pisanim putem najmanje 90 dana unaprijed.
4. Nakon datuma gašenja još 90 dana odgovara s 410 i kodom api.gone.

Pratite zaglavlje Deprecation u svojim zapisnicima ili nadzoru: to je najraniji znak da ruta koju koristite odlazi.

Praćenje promjena

Dnevnik promjena na ovom portalu navodi svako izdanje, s onim što je dodano i što je proglašeno zastarjelim. Prije nego što nadogradite vlastitu integraciju, usporedite njezin kod sa zapisima od verzije za koju ste je izgradili.