Verzie a kompatibilita

API má jednu hlavnú verziu, /v1, a tá len rastie. Integrácia napísaná dnes funguje ďalej aj vtedy, keď pribúdajú nové funkcie: nič, na čo sa spolieha, sa nepremenuje, neodstráni ani nedostane nový význam.

Číslo verzie

API má číslo verzie, napríklad 1.62.0. Mení sa s každým vydaním:

• vedľajšie číslo, keď sa niečo pridá: operácia, pole, udalosť;
• číslo opravy, keď sa opraví opis alebo text správy a nič iné sa nezmení.

Verziu, ktorú adresa poskytuje, si môžete kedykoľvek prečítať:

GET /v1/health má tiež version, ide však o verziu vydania Sursy, ktoré adresu obsluhuje, nie o verziu API.

Vedľajšiu verziu si nevyberáte: každú požiadavku obslúži aktuálna verzia. Vďaka pravidlám nižšie je to bezpečné.

Čo sa môže v rámci /v1 zmeniť

Tieto zmeny môžu prísť v ktorejkoľvek vedľajšej verzii. Integráciu napíšte tak, aby ju nenarušili:

• Nové operácie.
• Nové nepovinné parametre a polia požiadaviek. Požiadavky bez nich sa správajú ako predtým.
• Nové polia v odpovediach, objektoch a udalostiach.
• Nové hodnoty výčtov v odpovediach, napríklad nový stav karty alebo nový typ udalosti.
• Nové chybové kódy a nové hlavičky odpovedí.
• Menej prísne limity: väčšia maximálna dĺžka, širší rozsah.
• Preformulované texty message v chybách a preformulované opisy.

Čo musí váš kód zniesť

• Ignorujte polia, ktoré nepoznáte. Nezlyhajte, keď má odpoveď viac polí, než očakávate, a nepoužívajte prísne schémy, ktoré ich odmietnu.
• Prijímajte hodnoty výčtov, ktoré nepoznáte. Každý výčet v odpovedi sa môže rozšíriť. Neznámu hodnotu považujte radšej za „iné“ než za chybu.
• Preskočte typy udalostí, ktoré nepoznáte, vo webhookoch aj v streamoch.
• Neznáme chybové kódy spracujte podľa stavového kódu HTTP: pozri Chyby.
• Nespoliehajte sa na poradie polí v objektoch JSON ani na presné znenie správ.

Čo sa v rámci /v1 nikdy nezmení

• Cesta, parameter, pole ani hodnota výčtu sa nikdy nepremenuje ani neodstráni.
• Typ poľa sa nikdy nezmení a pole nikdy nedostane nový význam, napríklad nové jednotky.
• Požiadavka, ktorá sa prijíma dnes, sa neskôr neodmietne.
• Stavový kód úspešnej odpovede zostáva rovnaký.
• Chybové kódy si zachovávajú význam a pole detail v chybových odpovediach si zachováva tvar.
• Typy udalostí sa nikdy nepremenujú ani neodstránia a v ich data polia len pribúdajú.

Nekompatibilné zmeny

Ak by bola niekedy potrebná nekompatibilná zmena, vydá sa ako nová hlavná verzia, napríklad /v2, vedľa /v1. /v1 funguje ďalej bez zmeny a obe verzie bežia súbežne.

Keď sa má cesta vyradiť:

1. V špecifikácii sa označí ako deprecated a v zozname zmien sa uvedie s dátumom, keď sa vypne.
2. Jej odpovede obsahujú hlavičky Deprecation: true a Sunset: <date>.
3. Funguje ešte najmenej 180 dní od oznámenia. Organizácie, ktorých kľúče API ju používajú, dostanú písomné upozornenie najmenej 90 dní vopred.
4. Po dátume ukončenia odpovedá ešte 90 dní stavom 410 s kódom api.gone.

Sledujte hlavičku Deprecation vo svojich logoch alebo monitoringu: je to najskorší signál, že cesta, ktorú používate, sa ruší.

Ako byť v obraze

Zoznam zmien na tomto portáli uvádza každé vydanie s tým, čo pribudlo a čo sa označilo ako zastarané. Skôr než svoju integráciu aktualizujete, porovnajte jej kód so záznamami od verzie, pre ktorú ste ju vytvorili.