Verzie a deprecation

Ako vyvíjame Agent API bez toho, aby sme rozbili existujúce integrácie.

Stabilita

Agent API beží pod prefixom /v1/agent. V rámci v1 robíme len spätne kompatibilné zmeny: pridanie nového endpointu, nového voliteľného parametra alebo nového poľa v odpovedi. Tieto zmeny nevyžadujú žiadnu akciu na vašej strane.

Čo považujeme za kompatibilné

Pridanie endpointov, voliteľných request parametrov, nových polí v odpovediach a nových hodnôt enumov. Vaša integrácia by mala ignorovať neznáme polia a netreba ju viazať na poradie polí.

Breaking change

Zmeny, ktoré nie sú spätne kompatibilné (odstránenie/premenovanie poľa, zmena typu, zmena správania), vydáme pod novou verziou prefixu (napr. budúce /v2/agent). Predošlú verziu necháme bežať počas oznámeného deprecation obdobia.

Deprecation politika

Deprecácie oznamujeme vopred v changelogu s dátumom ukončenia podpory. Minimálne 90 dní pred vypnutím necháme starú verziu/endpoint funkčný. Kde to bude možné, deprekované endpointy vrátia hlavičku Deprecation a Sunset s dátumom.

Odporúčania

Sledujte changelog, pinujte sa na /v1/agent, parsujte odpovede tolerantne a používajte sandbox na overenie pred nasadením zmien.