Verze a kompatibilita

API má jednu hlavní verzi, /v1, a ta se pouze rozšiřuje. Integrace napsaná dnes funguje dál i s příchodem nových funkcí: nic, na co se spoléhá, se nepřejmenuje, neodstraní ani nedostane nový význam.

Číslo verze

API má číslo verze, například 1.62.0. Mění se s každým vydáním:

číslo vedlejší verze, když se něco přidá: operace, pole, událost;
číslo opravy (patch), když se opraví popis nebo text zprávy a nic jiného se nemění.

Verzi, kterou adresa obsluhuje, můžete kdykoli zjistit:

Kde	Co
`GET /openapi.json`	`info.version` specifikace
Každá událost kanálu událostí a každý webhook	`api_version`, verze, jejímuž schématu odpovídá `data`

GET /v1/health má také version, jde ale o verzi vydání Sursy, které adresu obsluhuje, ne o verzi API.

Vedlejší verzi si nevybíráte: každý požadavek obsluhuje aktuální verze. Díky níže uvedeným pravidlům je to bezpečné.

Co se může v /v1 změnit

Tyto změny mohou přijít v jakékoli vedlejší verzi. Napište svou integraci tak, aby ji nerozbily:

Nové operace.
Nové volitelné parametry a pole požadavků. Požadavky bez nich se chovají jako dřív.
Nová pole v odpovědích, objektech a událostech.
Nové hodnoty výčtů v odpovědích, například nový stav karty nebo nový typ události.
Nové chybové kódy a nové hlavičky odpovědí.
Méně přísné limity: větší maximální délka, širší rozsah.
Přeformulované texty message u chyb a přeformulované popisy.

Co musí váš kód snést

Ignorujte pole, která neznáte. Neselhávejte, když má odpověď více polí, než čekáte, a nepoužívejte přísná schémata, která je odmítají.
Přijímejte hodnoty výčtů, které neznáte. Každý výčet v odpovědi se může rozrůst. S neznámou hodnotou zacházejte jako s „jiné“, ne jako s chybou.
Přeskakujte typy událostí, které neznáte, ve webhoocích i ve streamech.
Neznámé chybové kódy zpracovávejte podle jejich stavového kódu HTTP: viz Chyby.
Nespoléhejte na pořadí polí v objektech JSON ani na přesné znění zpráv.

Co se v /v1 nikdy nezmění

Cesta, parametr, pole ani hodnota výčtu se nikdy nepřejmenuje ani neodstraní.
Typ pole se nikdy nezmění a pole nikdy nezíská nový význam, například nové jednotky.
Požadavek, který se přijímá dnes, se později neodmítne.
Stavový kód úspěšné odpovědi zůstává stejný.
Chybové kódy si zachovávají svůj význam a pole detail chybových odpovědí si zachovává svůj tvar.
Typy událostí se nikdy nepřejmenují ani neodstraní a do jejich data pole jen přibývají.

Nekompatibilní změny

Pokud bude někdy nekompatibilní změna potřeba, vyjde jako nová hlavní verze, například /v2, vedle /v1. /v1 funguje dál beze změny a obě verze běží souběžně.

Když má být některá cesta vyřazena:

Ve specifikaci se označí jako deprecated a v seznamu změn se uvede s datem, kdy bude vypnuta.
Její odpovědi nesou hlavičky Deprecation: true a Sunset: <date>.
Funguje ještě nejméně 180 dní po oznámení. Organizace, jejichž klíče API ji používají, dostanou písemné upozornění nejméně 90 dní předem.
Po datu ukončení odpovídá ještě dalších 90 dní 410 s kódem api.gone.

Sledujte hlavičku Deprecation ve svých protokolech nebo monitoringu: je to nejčasnější signál, že cesta, kterou používáte, bude zrušena.

Jak zůstat v obraze

Seznam změn na tomto portálu uvádí každé vydání s tím, co přibylo a co bylo označeno jako zastaralé. Než svou integraci aktualizujete, porovnejte její kód se záznamy od verze, pro kterou byla napsána.