API changelog: co publikovat a kdo to čte

API changelog je datovaný záznam každé změny, kterou by volající mohl zaznamenat, napsaný pro ty, kdo se s API integrují, ne pro tým, který ho vydává. Toto publikum z něj dělá jiný dokument než changelog produktu: čtenář rozhoduje, jestli jeho kód bude fungovat i příští měsíc. Většina selhává stejně, jako odfiltrovaná kopie interního release feedu, takže odstraněné pole leží vedle textové opravy se stejnou váhou, a nic z toho se nečte.

Co je API changelog?

Je to veřejný, datovaný deník změn v rozhraní, proti kterému ostatní napsali kód. Užitečný test, jestli tam něco patří, nemá nic společného s tím, jak velká byla změna interně. Ptá se, jestli by se správný volající, napsaný loni a od té doby nedotčený, mohl kvůli tomu chovat jinak. Tento test připouští některé velmi malé změny a vylučuje některé velmi velké.

Všechno níže předpokládá, že volající je mimo firmu a prakticky nedosažitelný jinak než přes tento dokument. Když je volajícím jiný tým ve stejné firmě, výpočet se změní natolik, že si zaslouží vlastní zpracování; interní API changelogy rozebírá, co to publikum potřebuje místo toho.

Jak napsat migrační průvodce API pokrývá tenhle poslední dokument celý; krátce řečeno, je to to, na co by měl odkazovat záznam o nekompatibilní změně, místo aby ho zkoušel nahradit.

Těchto pět je samostatných dokumentů se samostatnými životními cykly. Oznámení deprekace je slib s datem a patří i do changelogu, ale záznam changelogu se píše jednou, zatímco deprekace se sleduje až do jejího sunsetu. Jejich sloučení je důvod, proč se sunsety promeškávají.

Co patří do jednoho záznamu?

Šest věcí, a první tři jsou ty, které obvykle chybí. Změna, formulovaná v pojmech požadavku nebo odpovědi, ne interní komponenty. Jestli láme správného volajícího. Co musí volající udělat, včetně “nic”. Datum, kdy vstoupila v platnost. Verze nebo verze, kterých se to týká. Odkaz na průvodce migrací, pokud existuje.

Záznam, který říká “vylepšen endpoint accounts”, selhává na všech šesti. Záznam, který říká “pole accounts.type teď vrací individual tam, kde dřív vracelo personal; existující hodnoty zůstávají nezměněné u účtů vytvořených před 2. zářím; není potřeba žádná akce, pokud neporovnáváte řetězec”, odpovídá na všech šest v jedné větě.

Kategorizujte záznamy podle důsledku, ne podle oddělení. Tři štítky nesou téměř celou hodnotu: breaking, additive a fixed. Semantic Versioning už přesně definuje první dvě, a půjčit si jeho definice místo vymýšlení vlastních znamená, že čtenář, který zná semver, zná vaše štítky. Keep a Changelog nabízí delší sadu, pokud chcete, a jeho ústřední pravidlo tu platí silněji než kdekoli jinde: deník je pro lidi, a výpis titulků commitů jím není.

Čím se API changelog liší od release notes?

Release notes popisují, co produkt teď umí. API changelog popisuje, jaká je teď smlouva. Stejná vydaná práce často vytváří záznam v obou, formulovaný jinak, protože publika potřebují jiné věci: nový exportní formát je funkce pro uživatele a nová hodnota enum pro volajícího, který se na tomto poli přepíná.

Praktický důsledek je, že tyto dva nemohou být stejný feed s jiným stylem. Volající, který odebírá vše, co vydáváte, se nakonec odhlásí, a pak zmešká breaking change. Pokud publikujete jeden feed, filtrujte ho; pokud publikujete dva, zúžete ten pro API a nikdy do něj nepusťte marketingový záznam. Obě formy porovnáváme vedle sebe v changelog vs release notes.

Kde by měl API changelog žít?

Vedle referenční dokumentace, na stabilní URL, s každým záznamem individuálně adresovatelným přes fragment nebo vlastní cestu. Volající odkazují na záznamy v rozborech incidentů a interních tiketech, a záznam, na který nelze odkázat, skončí vložený jako snímek obrazovky místo toho.

Publikujte ho i jako strojově čitelný výstup, kromě stránky. JSON feed podle specifikace JSON Feed nebo RSS feed nestojí nic, jakmile se záznamy stanou strukturovanými daty, a je to právě to, co umožňuje klientovi zapojit vaše změny do vlastního release procesu. To je také část, která rozhoduje, jestli na tom někdo staví. GitHub dokumentuje své verze REST API hned vedle reference ze stejného důvodu: politika verzování je součástí rozhraní.

Jak vypadá dobrý záznam v praxi?

Tři záznamy ze stejného týdne, ve výše popsané formě:

2026-09-02  Breaking  v2
  `POST /invoices` teď odmítá `currency`, která neodpovídá měně účtu
  zákazníka, a vrací 422 místo tichého převodu. Volající, kteří
  spoléhali na převod, musí posílat měnu účtu. Týká se jen v2; v1
  zůstává beze změny až do sunsetu 2027-01-15.

2026-09-02  Additive  v1, v2
  `Invoice` získává časové razítko `settled_at`, null dokud není
  faktura vyrovnána. Není potřeba žádná akce. Klienti odmítající
  neznámá pole by měli být aktualizováni.

2026-08-31  Fixed  v2
  `GET /invoices?status=` vracel prázdnou stránku místo 400 pro
  neznámý status. Teď vrací 400 s akceptovanými hodnotami. Volající s
  překlepem dřív viděli nulu výsledků, teď vidí chybu.

Třetí je typ nejčastěji vynechávaný, protože interně je to oprava chyby. Pro volajícího, který kolem té prázdné stránky postavil retry, je to změna chování, a záznam je to, co brání tiketu do supportu. Štítek říká fixed a tělo říká, co by volající mohl zaznamenat, což je rozlišení, které drží deník poctivý, aniž by nafukovalo každou opravu na breaking change.

Jak se volající odebírají?

Dejte jim víc než jeden kanál, protože mají různé úkoly. Feed pro vývojáře, který chce všechno. E-mail pro toho, kdo chce jen breaking changes. Hlavičky odpovědi pro samotný kód, jediného odběratele, který nikdy nezapomene zkontrolovat: hlavička Sunset definovaná v RFC 8594 dává datum vyřazení do odpovědi, kde ji klientská knihovna může zalogovat.

Kanál, který většina týmů vynechává, je přímý. Pokud volající minulý týden použil pole, které měníte, víte, kdo to je, a e-mail na tyto účty má větší hodnotu než jakékoli obecné vysílání. Je to stejná disciplína jako uzavření smyčky zpětné vazby od zákazníka, aplikovaná na změnu, o kterou nikdo nepožádal: postižení jsou informováni jednotlivě, a všichni ostatní dostanou feed. Webhook je čtvrtý kanál s vlastním způsobem selhání, který stojí za to znát, než se na něj spolehnete: changelogy webhooků pokrývá, proč se změna payloadu tam rozbíjí potichu, bez volajícího, který by mohl odmítnout nový tvar.

Jak napsat záznam pro breaking change?

Začněte porušením, ne důvodem. Volající, který prochází deset záznamů, musí v první větě vědět, jestli ho tento bude stát práci. Pak datum, dotčené verze, migraci, a termín, pokud staré chování mizí místo aby se měnilo.

Dejte stejný obsah do oznámení deprekace, hlavičky odpovědi a přímého e-mailu, formulovaný konzistentně, a dejte všem čtyřem stejné datum. Rozpor mezi nimi je chyba, která mění plánovanou změnu v incident, protože volající, který četl jen jeden z nich, jedná podle špatného data. Co je breaking change pokrývá samotné rozhodnutí, a jak deprekovat API pokrývá harmonogram, který následuje.

V changeloop se změna API stane záznamem, když je pull request sloučen, někdo upraví a schválí koncept, a záznam se publikuje na feedu a widgetu ve stejný moment, kdy je o tom informován volající, jehož zpětná vazba z widgetu se stala GitHub issue, které ten pull request uzavírá, přímo v tom issue. Krok revize je to, na čem tu záleží: API changelog je smluvní dokument, a žádný koncept by neměl dosáhnout volajícího, aniž by ho přečetl člověk.

FAQ

Potřebuje každá změna API záznam v changelogu? Každá změna, kterou by správný volající mohl zaznamenat, ano, včetně těch, které považujete za interní. Změny bez pozorovatelného efektu na požadavek nebo odpověď ne, a jejich přidávání trénuje čtenáře, aby text jen přelétli.

Měl by API changelog žít v dokumentaci, nebo na marketingovém webu? V dokumentaci, hned vedle reference. Čtenář je tam obvykle už tak jako tak, a changelog na marketingovém webu mívá tendenci získat publikum, pro které nebyl napsaný.

Jak daleko do minulosti by měl sahat? Neomezeně. Záznamy jsou citovány o roky později v rozborech incidentů, a oříznutý deník láme tyto odkazy. Stránkujte místo ořezávání.

Potřebuji samostatný changelog pro každou verzi API? Ne, jeden deník s polem verze na záznam se snáz čte a prohledává. Filtrování podle verze je funkce stránky, ne důvod dokument dělit.

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