Jak napsat migrační průvodce API

Migrační průvodce API je dokument, který mění nekompatibilní změnu ve checklist místo výpadku: co se změnilo, co s tím udělat, a do kdy. Záznam changelogu může nekompatibilní změnu pojmenovat ve dvou větách; migrační průvodce je to, co volající strana skutečně otevře, když tyto dvě věty říkají „tohle tě rozbije” a ona potřebuje přesně vědět, co upravit. Publikovat záznam bez průvodce je způsob, jak se volající strana o nekompatibilní změně dozví z ticketu podpory místo z dokumentu napsaného přesně proto, aby tomu zabránil.

Co je migrační průvodce API?

Dokument krok za krokem, který provede volající stranu od staré podoby API k nové, napsaný pro někoho, kdo má kód k úpravě, ne pro někoho, kdo se ještě rozhoduje, zda API vůbec přijme. Na tomhle rozdílu záleží: migrační průvodce předpokládá existující integraci a existující produkční provoz, takže musí pokrýt rollback, částečnou migraci a to, jak poznat, že migrace uspěla, nic z čeho nepotřebuje průvodce pro první integraci.

Migrační průvodce obvykle stojí mezi posledními dvěma: oznámení deprekace spustí hodiny, a migrační průvodce je to, čím se volající strana řídí předtím, než tyto hodiny doběhnou.

Kdy změna potřebuje migračního průvodce, a ne jen záznam changelogu?

Když je mezi starým a novým chováním víc než jeden krok, nebo když změna zasahuje dost míst volání, že volající straně víc pomůže propracovaný příklad než popis. Co je nekompatibilní změna, a jak ji vydat pokrývá test, jestli je změna nekompatibilní; pokud je odpověď ano, druhá otázka zní, jestli je oprava jednořádková úprava, nebo skutečná migrace. Přejmenované pole zvládne volající strana jen se záznamem changelogu. Změna v autentizaci, stránkování nebo zpracování chyb si téměř vždy zaslouží průvodce, protože správný náhradní kód není zřejmý z jednovětého popisu.

Co musí migrační průvodce obsahovat?

Pět věcí, a vynechání kterékoli z nich je způsob, jak se z průvodce stane stránka, kterou volající strana přečte jednou a pak se vrátí k pokusu a omylu. Starý kód, ukázaný tak, jak by skutečně vypadal v projektu. Nový kód, ukázaný stejně, ne jako abstraktní popis rozdílu. Co se rozbije, když se nic nezmění, řečeno jasně, protože „nic” je platná a běžná odpověď, kterou volající strana přesto potřebuje slyšet explicitně. Způsob, jak ověřit, že migrace fungovala, jako pole odpovědi nebo stavový kód ke kontrole. A časový plán: kdy staré chování přestane fungovat, a jestli jsou mezitím dostupné obě podoby.

## Migrace měnových polí z float na integer (v3.0.0)

Před:
  { "amount": 19.99 }

Po:
  { "amount": 1999 }  // nejmenší měnová jednotka (haléře)

Co se mění: `amount` je teď celé číslo v nejmenší jednotce měny účtu.
Kód, který čte `amount` jako float, bude od 1. října 2026 číst
hodnotu 100x příliš vysokou.

Ověření: po migraci by účtování 19,99 mělo znít `amount: 1999`, ne
`amount: 19.99`.

Časový plán: v2 nadále vrací float do 15. ledna 2027. v3 vrací celá
čísla od spuštění. Obě verze jsou teď aktivní.

Každá z těchto pěti věcí odpovídá na otázku, kterou by volající strana jinak musela hádat nebo se na ni ptát podpory, a to je přesně náklad, který migrační průvodce ušetří.

Kdo by ho měl napsat, a kdy?

Ten, kdo změnu navrhl, ve stejný okamžik, kdy vychází, ne tým podpory, který ho později rekonstruuje z ticketů. Ten, kdo rozhodnutí učinil, ví, na které části starého chování se nikdo neměl spoléhat a které byly náhodnou smlouvou; průvodce napsaný později někým bez tohoto kontextu má tendenci buď příliš vysvětlovat zjevné, nebo minout ten jeden hraniční případ, který lidi skutečně rozbije. Průvodce a záznam changelogu, který oznamuje nekompatibilní změnu, by měly vyjít společně, přičemž záznam odkazuje na průvodce místo toho, aby ho opakoval.

Jak to souvisí s verzováním a changelogem API?

Přímo: migrační průvodce je podrobná verze toho, co záznam MAJOR v semantic versioning a váš changelog jen shrnuje v jedné větě. Záznam changelogu říká, že změna je nekompatibilní a zhruba, co se změnilo; migrační průvodce je odkaz, který by tento záznam měl nést. Changelog API: co publikovat a kdo ho čte uvádí migrační průvodce jako jeden z pěti dokumentů, které API udržuje, každý odpovídá na jinou otázku; tenhle odpovídá na „jak se skutečně dostanu z A do B”, a zaslouží si vlastní stránku právě proto, že tahle odpověď je obvykle na záznam changelogu příliš dlouhá.

Jak dlouho by měl migrační průvodce zůstat zveřejněný?

Přinejmenším tak dlouho, dokud je staré chování dosažitelné, a ideálně i poté. Volající strana, která migruje o osmnáct měsíců později, poté co ignorovala tři oznámení deprekace, průvodce pořád potřebuje, a smazat ho v den, kdy se staré chování vypne, jen zaručuje, že volající strana, která ho potřebuje nejvíc, ho nenajde. Drž ho na stabilní URL a aktualizuj sekci časového plánu, místo abys stránku stahoval. Vlastní upgrade guide od Stripe je veřejný příklad tohoto vzoru: jedna stránka, udržovaná aktuální vydání za vydáním, místo nového dokumentu pro každou verzi, který zestárne ve chvíli, kdy vyjde další. Váš vlastní průvodce patří někam stejně snadno dohledatelně, vedle dokumentace, kterou volající strana už čte, ne zahrabaný v archivu blogu.

FAQ

Potřebuje každá nekompatibilní změna migračního průvodce? Ne. Změna, kterou volající strana zvládne jen se záznamem changelogu, jako jedno přejmenované pole se zjevnou náhradou, nepotřebuje samostatného průvodce. Změna, která zasahuje víc míst volání nebo vyžaduje propracovaný příklad, ano.

Měl by migrační průvodce žít u dokumentace API, nebo v changelogu? U dokumentace, odkazovaný ze záznamu changelogu. Záznam je to, co odběratelka vidí první; průvodce je to, co potřebuje, jakmile se rozhodne jednat, a patří vedle referenčních materiálů, které volající strana už používá.

Jaký je rozdíl mezi migračním průvodcem a oznámením deprekace? Oznámení deprekace deklaruje, že něco zmizí, a do kdy. Migrační průvodce jsou instrukce, co s tím udělat. Oznámení deprekace bez odkazovaného migračního průvodce dá volající straně termín, aniž by jí řeklo, jak ho splnit.

Mělo by se během migračního okna dokumentovat staré i nové chování zároveň? Ano, pokud možno na stejné stránce, aby volající strana viděla přesně, co se změnilo, místo aby si to skládala ze dvou samostatných dokumentů napsaných v různých časech.

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