Interní API changelogy: co se mění pro druhý tým

Každý jiný článek v tomto hubu předpokládá, že volající API je mimo firmu: vývojářka zákaznice, partnerka, někdo, kdo si dokumentaci našel sám. Spousta API má úplně jiný typ volajícího, tým ve vedlejší místnosti nebo o dvě patra dál, a to mění výpočet toho, co mu changelog dluží, protože zpráva na Slacku ho zastihne a support ticket se obvykle vůbec neotevře. Většina týmů z toho usuzuje, že interní API changelog nepotřebují. Co ve skutečnosti potřebují, je jiný.

Co dělá changelog interního API jiným než veřejný?

Publikum je dosažitelné přímo, což odstraňuje hlavní důvod, proč většina veřejných API changelogů existuje: vysílání volajícím, které nelze kontaktovat jednotlivě. Tým vlastnící interní API obvykle přesně ví, které další týmy ho volají, někdy až na konkrétní službu. To dělá z cílené zprávy, ne veřejného feedu, přirozenou výchozí volbu, a proto interní API tak často skončí úplně bez changelogu: vlastnící tým upozorní dva tři týmy, které si pamatuje, s předpokladem, že to pokryje všechny.

Proč selhává „prostě upozorníme týmy, které nás volají”?

Protože množina volajících nikdy není tak malá nebo statická, jak si ji vlastnící tým pamatuje. Služba postavená pro jednu konzumentku získá druhého volajícího o šest měsíců později, přes integraci, kterou nikdo neoznámil, a mentální seznam „kdo nás volá” vlastnícího týmu je teď špatný, aniž by si toho kdokoli všiml. Selhání je obyčejné a běžné, výchozí výsledek spoléhání na paměť místo na záznam, ne známka toho, že byl někdo nedbalý. Co je breaking change rozebírá, jak rozhodnout, jestli změna API vůbec počítá jako breaking; interní případ přidává druhou, těžší otázku navrch, totiž vědět, koho informovat.

Potřebuje interní API vůbec stránku changelogu ve veřejném stylu?

Obvykle ano, i když primární kanál je přímý. Stránka dá přímé zprávě na co odkázat, takže oznámení může zůstat krátké („breaking change v /v2/accounts, detaily zde”) místo pokusu protáhnout celé vysvětlení do chatové zprávy, která odscrolluje pryč. Stane se také tím, co může nový tým, nebo tým, který přímou zprávu minul, zkontrolovat, když jejich integrace přestane fungovat a snaží se přijít na to proč. Stránka nemusí být vypulírovaná ani veřejná; musí být odkazovatelná a přežít Slack vlákno, které ji oznámilo.

Kdo vlastně udržuje seznam volajících?

Vlastnící tým, a musí se to brát jako skutečný artefakt, ne jako kmenové vědění. Nejlevnější verze je soubor přímo v repozitáři API, krátký seznam konzumujících služeb s odpovědnou osobou na záznam, aktualizovaný pokaždé, když vznikne nová integrace, stejná disciplína jako u jakéhokoli deklarování závislosti. Alternativa, ptát se okolo před každým breaking change, funguje až do té jedné chvíle, kdy někdo zapomene zeptat se správné osoby, a interní API, které se potichu rozbije pro jeden tým, je menší incident než veřejné, ale pořád je to incident, obvykle objevený vlastní pohotovostí toho týmu místo vlastníkem API.

# consumers.yml
- service: billing-service
  owner: "#team-billing"
  since: 2026-03-01
- service: reporting-pipeline
  owner: "#team-analytics"
  since: 2026-06-14

Takový soubor mění „koho musíme upozornit” z otázky na vyhledání. Nástroje postavené přesně pro tenhle problém, jako service catalog od Backstage, modelují API jako plnohodnotné entity s deklarovanými konzumenty ze stejného důvodu: jakmile má organizace dost interních služeb, ničí paměť o tom, kdo co volá, už sama o sobě nezůstává přesná, a záznam musí držet něco jiného. Dokumentace k nástroji, který už interně provozujete, je obvykle to správné místo, kde se podívat, než stavíte vlastní řešení.

Co patří do interního záznamu changelogu, co by veřejný nepotřeboval?

Víc provozní konkrétnosti, protože čtenářka je jiná inženýrka, která na tom bude jednat v rámci stejné infrastruktury, ne to číst jako shrnutí. Ve kterých prostředích je změna živá a kdy, protože interní služby jsou často povyšovány přes fáze, které veřejný volající nikdy nevidí. Jestli změna vyžaduje aktualizaci konfigurace nebo klientské knihovny na straně konzumentky, formulovanou jako příkaz, pokud existuje. A protože interní volající mohou oprava často koordinovat přímo s vlastnícím týmem, jmenovaný kontakt místo support kanálu: „napiš @marii, pokud tohle něco rozbije” je v interním záznamu naprosto rozumný řádek a ve veřejném API changelogu divný.

Platí to stejně pro changelog uvnitř monorepa?

Zostřuje to stejný problém, místo aby ho nahrazovalo. Changelogy monorepa rozebírá, kdy balíček potřebuje vlastní changelog; interní API, které je jedním z několika balíčků v monorepu, přesto potřebuje, aby jeho konzumenti byli sledováni explicitně, protože sdílet repozitář s tím, kdo ho volá, neznamená, že si všimnou změny, dokud jim něco neřekne, aby se podívali. Blízkost v repu není totéž co blízkost v pozornosti.

FAQ

Potřebuje čistě interní API changelog, pokud má jen jednoho volajícího? Sotva, a přímá zpráva tomu jedinému týmu obvykle stačí. Changelog se vyplatí, jakmile je volajících víc než jeden, nebo jakmile seznam volajících vlastnící tým jednou překvapil, protože to je znamení, že paměť sama už není spolehlivá.

Měly by interní změny API projít stejnou revizí jako veřejné? Formulace může být lehčí, protože čtenářka je kolegyně, ne externí volající, ale rozhodnutí, jestli je změna breaking, si zaslouží stejnou péči v obou případech. Interní volající má pořád produkční kód, který závisí na starém chování.

Jak zjistit, kdo volá interní API, pokud se to nikdy nesledovalo? Serverové logy nebo data provozu ze service mesh jsou upřímná odpověď, pokud se nikdy neudržoval registr konzumentů; ber to objevení jako moment, kdy jeden začít vést, ne jako jednorázový úklid.

Stačí zpráva na Slacku, nebo interní změna přesto potřebuje formální záznam v changelogu? Obojí, pro cokoli, co není čistě přídavné. Zpráva je to, co se přečte včas; záznam je to, co tým zkoumající problém o týdny později, který zprávu nikdy neviděl, může přesto najít.

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, Srovnání nástrojů pro changelog