Jak deprekovat API bez ztráty vývojářů

Deprekovat API znamená oznámit, že něco dnes ještě funguje a k oznámenému datu funkčnost přestane, a pak dodržet obě poloviny toho slibu. Většina deprekací selhává na druhé polovině: datum tiše posune, nebo přijde, a volající, kteří oznámení nikdy neviděli, se to dozví z chyby. Deprekace je dokončena, když každý postižený volající buď migroval, nebo mu bylo individuálně řečeno, že to neudělal.

Co je deprekace API?

Deprekace je období mezi oznámením, že endpoint, pole nebo verze zmizí, a jejich skutečným odstraněním. Během tohoto období staré chování dál funguje, dokumentace říká, že odchází, a každá odpověď nese strojově čitelné varování. Odstranění je oddělená, pozdější událost, často nazývaná sunset. Tyto dva se pletou, a to plete je místem, kde vzniká škoda: «deprecated» začne znamenat «možná už zmizelo», a volající přestanou důvěřovat oběma slovům.

Jak dlouho by mělo trvat období deprekace?

Dost dlouho, aby se volající dozvěděl a udělal práci, měřeno od okamžiku, kdy ho oznámení zasáhlo, ne od okamžiku, kdy jste ho napsali. Devadesát dní je běžné minimum pro veřejné webové API. Dvanáct měsíců je normální pro cokoli zabudované do softwaru, který instalují koncoví uživatelé, protože oprava musí projít i jejich procesem vydání. Pokyny Google k verzování, AIP-185, žádají přiměřené přechodné období a doporučují 180 dní dokonce i před odstraněním beta funkcí, a Kubernetes dokumentuje svou politiku deprekace v počtu vydání místo měsíců, což je správná jednotka, když se vaši volající aktualizují podle verze.

Vyberte období, zapište ho jako politiku, a přestaňte o něm rozhodovat u každé změny. Zveřejněná politika mění každou deprekaci z vyjednávání na uplatnění pravidla.

Zapsání politiky deprekace pokrývá začátek okna; ukončování verze API pokrývá oddělené oznámení potřebné na konci, když období skutečně vyprší a verze přestane fungovat.

Harmonogram deprekace

Čtyři data, oznámená společně v první den. Každé je samostatný záznam changelogu při příchodu, takže se příběh vypráví čtyřikrát každému, kdo čte jen changelog.

1. Oznamte. Záznam říká, co se deprekuje, proč, co to nahrazuje, a datum sunset. Dokumentace staré věci získá banner odkazující na migraci. Odpovědi získají hlavičky popsané níže.
2. Připomeňte, v polovině cesty. Druhý záznam, a přímá zpráva každému volajícímu, který stále používá staré chování. To je krok, který potřebuje data o používání: pokud nemůžete vypsat, kdo stále volá deprekovaný endpoint, nemůžete to udělat, a vyplatí se to opravit před další deprekací.
3. Brownout, krátce před datem. Vraťte chyby pro staré chování na krátké okno, hodinu nebo den, pak obnovte. Volající, kteří zmeškali každé oznámení, se to dozví teď, dokud je ještě čas. GitHub použil naplánované brownouty před vyřazením ověřování heslem pro API, a je to nejúčinnější jednotlivý krok v tomto seznamu.
4. Sunset. Odstraňte to. Chyba, která to nahrazuje, pojmenuje náhradu a odkazuje na migrační příručku. Udržujte chybu na místě dlouho; 404 volajícímu nic nesdělí.

Co by mělo oznámení o deprekaci říkat?

Oznámení o deprekaci říká, co odchází, kdy se zastavuje, co použít místo toho, a koho se to týká. Zde je forma, vyplněná:

GET /v1/reports/daily je deprekován a přestává fungovat 1. března 2027. Nahrazuje ho GET /v2/reports?granularity=day, který vrací stejná data se stabilním schématem a stránkováním. Týká se 214 integrací, které volaly endpoint v1 za posledních 30 dní; pokud je vaše jedna z nich, dostanete toto oznámení také e-mailem. Migrační příručka: [odkaz]. Nic se nemění do 1. března 2027. Od tohoto data endpoint v1 vrací 410 Gone s odkazem na tento záznam.

Každá věta nese něco, co čtenářka potřebuje. Počet postižených integrací říká každé čtenářce, zda má pokračovat ve čtení. «Nic se nemění do» je věta, která umožňuje nepostiženým zavřít záložku. Stránka příklady changelogu shromažďuje záznamy od týmů, které tuto formu píší konzistentně, a vyplatí se přečíst tři, než napíšete svůj první vlastní.

Jaké hlavičky by měl posílat deprekovaný endpoint?

Posílejte Deprecation, Sunset a Link na nástupce, v každé odpovědi z deprekovaného endpointu, ode dne oznámení. Hlavička Deprecation nese datum, kdy deprekace vstoupila v platnost; hlavička Sunset nese datum, kdy endpoint přestává odpovídat; Link: <url>; rel="successor-version" ukazuje, co použít místo toho.

HTTP/1.1 200 OK
Deprecation: @1756425600
Sunset: Mon, 01 Mar 2027 00:00:00 GMT
Link: <https://api.example.com/v2/reports>; rel="successor-version"
Link: <https://example.com/changelog/daily-reports>; rel="deprecation"

Většina volajících hlavičky sama nikdy nepřečte. Jejich hodnota je v tom, že HTTP klient, brána nebo monitoring volajícího mohou, což promění vaši deprekaci ve výstrahu na jejich straně místo stránky na té vaší. SDK, které dodáváte, by měly logovat varování, když jednu uvidí.

Kdo byl informován, a jak to víte?

Toto je krok, který rozhoduje, zda je sunset klidný nebo se stane incidentem podpory, a je to nejtěžší udělat jen s changelogem. Záznam changelogu informuje každého, kdo changelog čte. Deprekace musí zasáhnout konkrétní lidi, jejichž kód selže, a obvyklý způsob, jak je najít, jsou stejná data o používání, která potřebuje připomínka v polovině cesty: API klíče, aplikace nebo účty, které nedávno volaly deprekované chování.

Smyčka, kterou provádíme: záznam se sestavuje z pull requestu, který přidává deprekaci, člověk revizuje formulaci a datum, a jakmile je zveřejněn, samotný záznam je oznámení. Kdokoli, jehož zpětná vazba z widgetu k tomu problému nebo žádost o náhradu se stala GitHub issue, které ten pull request uzavírá, dostane v tom issue komentář, který říká, že to bylo vydáno, s odkazem na záznam. Kanál a widget obsluhují stejný záznam všem ostatním, spolu s každým dalším záznamem v API changelogu. Co neděláme, je nechat deprekaci stát se «vydanou» předtím, než ji člověk zveřejnil; oznámení se špatným datem je horší než žádné oznámení.

Ať jsou vaše nástroje jakékoli, otázka, na kterou musíte umět odpovědět v den sunset, zní: kteří volající to stále používali minulý týden, a kterým z nich jsme to řekli přímo? Pokud je odpověď «napsali jsme o tom příspěvek», sunset není připraven.

Jaký je rozdíl mezi deprekací a verzováním?

Verzování je způsob, jak udržujete staré chování dostupné, zatímco existuje nové; deprekace je způsob, jak vyřazujete staré. Nová verze API bez politiky deprekace pro předchozí je závazek provozovat obě navždy. Deprekace bez verzování je breaking change se zpožděním. Potřebujete oba, a verze je snazší polovina. GraphQL je výjimka, kterou stojí za to pojmenovat: obvykle tam vůbec není žádné číslo verze ke zvýšení, a deprekace schématu GraphQL pokrývá, jak jedno sdílené schéma místo toho vyřadí pole direktivou.

FAQ

Měl by deprekovaný endpoint dál fungovat přesně jako předtím? Ano, do data sunset. Jedinými povolenými změnami jsou přidané hlavičky a, blíže konci, naplánovaný brownout, který jste oznámili předem.

Jaký stavový kód by měl vracet vyřazený endpoint? 410 Gone, s tělem a hlavičkou Link ukazující na náhradu a záznam changelogu. 404 říká, že URL nikdy neexistovala, což je nepravdivé a nepomáhá to.

Lze zkrátit období deprekace? Pouze z bezpečnostních důvodů. Pokud je staré chování zneužitelné, řekněte to, zkraťte období, a informujte každého postiženého volajícího přímo, místo spoléhání se na changelog.

Musím deprekovat pole, nebo jen celé endpointy? Pole, parametry, hodnoty enum, výchozí hodnoty a hlavičky všechny potřebují stejné zacházení, protože každé z nich může rozbít korektního volajícího. Odstraněné pole je nejběžnější deprekace a nejčastěji přeskočená.

Technická tvrzení v tomto článku nikdo nezávisle neověřil. Pokud tu něco nesedí, dej nám vědět a opravíme to.

Související na changeloop: Dokumentace pro vývojáře, Příklady changelogu