4 zásady, jak navrhnout REST API odolné vůči změnám dat

Mnoho týmů si myslí, že vyřeší změny tím, že přidá „/v1" do cesty. To je nejmenší část problému. Skutečné verzování znamená, že stará verze zůstane funkční, dokud ji klienti používají. To v praxi znamená: nová pole přidávejte jako nepovinná, stará pole nikdy nemažte – jen je označte jako zastaralá a přestaňte je plnit. Pokud musíte změnit typ nebo význam pole, vytvořte pole nové s odlišným názvem a to staré ponechte prázdné. Klient, který ho ignoruje, dostane odpověď, která pro něj dává smysl.

Základ je popsat proč, ne co. Samotný diff ukazuje, které řádky se změnily, takže psát „změněna podmínka v cyklu" je zbytečné. Užitečná je informace, kterou z kódu nevyčtete: „cyklus končil o jedna dřív a poslední záznam se neukládal". První řádek držte krátký, do zhruba padesáti znaků, zbytek rozveďte v těle zprávy po prázdném řádku. Tím získáte přehled v logu i detail pro toho, kdo bude pátrat po příčině.

Přístupnost není volitelná. Kontrast textu vůči pozadí musí být dostatečný, ovládací prvky musí být dosažitelné klávesnicí a stav nesmí být sdělen pouze barvou. Tlačítko nesmí být menší než prst, jinak ho na telefonu netrefíte. U modálních oken vždy zajistěte, aby se fokus přesunul dovnitř a po zavření vrátil zpět. Tohle jsou věci, které vývojář zvládne bez grafika a které rozhodují o tom, jestli aplikace působí použitelně.

Vyhýbejte se neurčitým slovům, která nic neříkají: „oprava chyby", „vylepšení", „různé". Pokud opravdu nevíte, co změna dělá, je to signál, že jste ji neměli commitovat. Stejně tak nedávejte do zprávy odkazy na interní systém, jehož význam za rok zmizí. Místo čísla tiketu napište větu, která popisuje podstatu – číslo může být doplněk, ne náhrada sdělení.

Většina vývojářů řeší UI/UX až ve chvíli, kdy je logika hotová a zbývá „to nějak obalit". Přesně tam vzniká nejvíc problémů. Rozhraní, které dává smysl programátorovi, nemusí dávat smysl člověku, který aplikaci otevře poprvé. Základem je pochopit, že design není dekorace, ale způsob, jak řídit pozornost a snižovat počet rozhodnutí, která musí uživatel udělat.

Nakonec počítejte s tím, že některé změny přijdou nečekaně. Proto dokumentujte nejen aktuální stav, ale i to, co je zastaralé a kdy zmizí. Zaveďte deprecation hlavičky nebo pole, která upozorní na blížící se změnu. API, které umí říct „tudy už ne", je pro klienty srozumitelnější než tiché rozbití. Návrh pro budoucnost není složitý — je jen o tom nedělat unáhlená rozhodnutí, která se budou těžko vracet.

Prvním krokem je rozdělit repozitář na dva. V repozitáři s kódem ponechte pouze výchozí hodnoty, které jsou bezpečné pro všechny, a šablony konfiguračních souborů. Skutečné hodnoty pro vývoj, test a produkci patří do repozitáře s konfigurací. Tím získáte dvě nezávislé historie. Kód se dá kdykoli vrátit zpět, aniž byste s sebou táhli změny prostředí. Konfiguraci lze měnit bez nového buildu a bez zbytečného čekání na pipeline.

Do odpovědi vždy přidejte metadata: celkový počet (jen pokud ho umíte spočítat bez drahého COUNT(*) přes celou tabulku), odkaz na další stránku a informaci, zda existuje předchozí. U kurzorové paginace počet záznamů často vynechte úplně – je to poctivější než vracet číslo, které trvá sekundy. Limity držte nízko (například 20–100) a vynucujte je na serveru, ne v dokumentaci.

Jedna změna, jeden commit Nejčastější chyba je slepení nesouvisejících úprav do jednoho commitu. Opravíte překlep v textu, přidáte novou funkci a ještě upravíte konfiguraci – a výsledkem je změť, kterou nelze zpětně rozumně rozdělit. Když pak potřebujete vrátit jen opravu překlepu, musíte revertovat i funkci. Rozdělte práci na menší celky ještě před commitem, klidně pomocí příkazu, který do indexu přidá jen vybrané části souboru. Menší commity se snáz čtou, snáz se z nich staví historie a snáz se v nich hledá.

Při návrhu se vyplatí myslet na to, co bude volitelné a co povinné. Nová pole přidávejte jako nepovinná a v odpovědích je vracejte vždy, i když jsou prázdná. Klient, který je ignoruje, funguje dál. Naopak odebrání pole nebo změna jeho typu je breaking change, která si žádá novou verzi. Typickým začátečnickým krokem je přidat nové pole jako povinné — to okamžitě rozbije všechny staré klienty, kteří ho neposílají.

Užitečný zvyk je číst si vlastní zprávu před odesláním a představit si, že ji vidíte poprvé bez kontextu. Pokud nedokážete říct, čeho se změna týká a jaký problém řeší, přepište ji. Držte jednotný jazyk a čas – buď rozkazovací způsob („oprav", „přidej"), nebo oznamovací, ale nemíchejte to. Konzistence je to, co dělá historii čitelnou jako celek, ne jednotlivé řádky.