Co potřebujete vědět, než poprvé zavoláte API?

Mezi typické začátečnické chyby patří posílání klíče v adrese místo v hlavičce, zapomenutá hlavička s typem obsahu nebo záměna metody GET za POST. Další častou chybou je příliš rychlé opakování požadavků, které server odmítne kvůli limitu. Pokud narazíte na limit, zpomalte a přidejte prodlevu mezi voláními. Dokumentaci čtěte průběžně, ne až když něco nefunguje. Většina API má jasně popsané parametry, formát odpovědi i chybové stavy. Naučit se číst dokumentaci je stejně důležité jako umět odeslat požadavek.

Častou chybou je dokumentace psaná z pohledu backendu. Popisuje, co všechno server umí, ale ne to, co frontend potřebuje zjistit. Pište ji tak, aby odpovídala na otázky: Jak získám data pro výpis? Jak poznám, že požadavek selhal kvůli oprávnění? Jak stránkovat výsledky? Jaký je formát data a času? Bez těchto odpovědí vzniká zbytečná komunikace a zdržení. Pokud tým používá nástroj pro prohlížení API, udržujte v něm aktuální příklady i popisy chyb.

Základem je pochopit čtyři věci: metodu, adresu, hlavičky a tělo požadavku. Metoda GET slouží ke čtení dat, POST k vytváření, PUT a PATCH k úpravám a DELETE k mazání. Adresa určuje, na jaký zdroj se ptáte. Do hlaviček patří informace o formátu odpovědi a často také autorizační klíč. Tělo požadavku se posílá jen u metod, které něco vytvářejí nebo mění. Pokud tyto čtyři části popletete, server vrátí chybu a vy budete zbytečně hledat problém jinde.

Pozor na autentizaci. Tokeny mají omezenou platnost a v Postmanu je snadné zapomenout, že uložený token vypršel. Projevuje se to chybou 401, kterou lidé mylně hledají v logice aplikace. Stejně tak se vyplatí hlídat, zda posíláte data jako JSON s hlavičkou Content-Type: application/json. Když hlavička chybí, server tělo neparsuje a vrátí chybu, která vypadá jako problém s daty, ale jde jen o formát požadavku.

Nakonec nastavte krátkou revizi pyramidy při každém větším plánování. Stačí půl hodiny a otázka, zda rozložení testů odpovídá aktuálním rizikům. Pokud ne, upravte ho hned, dokud je změna malá. Pyramida, která se hýbe spolu s požadavky, zůstává užitečným nástrojem. Pyramida, která se hlídá jen podle počtu testů, se dřív nebo později stane jen dalším místem, kde se hromadí práce, kterou nikdo nechce udržovat.

Testy pište průběžně, ne až na konci. Postman umí spustit celou kolekci najednou a ukázat, které požadavky prošly a které ne. Tím odhalíte závislosti mezi voláními: vytvoření záznamu, jeho načtení, úprava a smazání. Pokud testy spouštíte v nesprávném pořadí, dostanete falešné chyby. Do kolekce proto zařaďte i úklidová volání, která po sobě uklidí data, jež testovací běh vytvořil.

První konkrétní krok: oddělte reprezentaci od identity. Nikdy neposílejte klientům interní databázové klíče jako primární identifikátor v URL. Místo „/objednavky/4711" použijte stabilní, veřejný identifikátor, který si sami generujete a který přežije migraci tabulek. Když se datový model změní – sloučíte tabulky, přejdete na UUID, rozdělíte entitu – veřejné ID zůstane stejné a klienti nic nepoznají.

Než začnete posílat požadavky na cizí API, potřebujete dvě věci: vědět, co to API vlastně je, a mít nástroj, kterým požadavek odešlete. API je rozhraní, přes které spolu komunikují dva programy. Vy pošlete požadavek na určitou adresu, server odpoví daty. Většina moderních API pracuje přes HTTP a vrací odpověď ve formátu JSON. Pro začátek si vystačíte s terminálem a nástrojem curl nebo s jednoduchým klientem, který umí posílat HTTP požadavky. Vyhněte se psaní vlastního kódu, dokud si požadavek nevyzkoušíte ručně.

Příklady a schémata místo dlouhých popisů Největší chybou je dokumentace bez příkladů. Jeden konkrétní požadavek a odpověď řeknou víc než odstavec textu. U složitějších struktur se vyplatí sdílené schéma, na které se endpointy odkazují. Tím se zabrání tomu, aby se stejný objekt popisoval na pěti místech různě. Pokud se schéma změní, upraví se jednou a všichni to vidí. Vyhněte se ale kopírování celých odpovědí do dokumentace ručně; text zastará a nikdo si toho nevšimne.

Testování aplikací, které závisí na datech a vazbách z externích služeb, je obtížné, pokud tyto služby nejsou dostupné. Místo čekání na obnovení připojení nebo na testovací prostředí je efektivnější vytvořit izolované prostředí, kde data i vazby simulujete. Nejde o obcházení testů, ale o jejich zrychlení a zpřesnění. Základem je uvědomit si, které vstupy a výstupy aplikace skutečně potřebuje, a ty nahradit věrnými atrapami.

Dokumentace REST API není formalita pro archiv. Je to pracovní nástroj, který drží frontend a backend u stejných předpokladů. Pokud chybí, začnou vznikat dohady: jaký formát data poslat, co znamená která chybová odpověď a proč jeden endpoint vrací jinou strukturu než druhý. Výsledkem jsou zbytečné opravy, zpoždění a přepisování hotových částí. Dokumentace má být proto součástí vývoje, ne něčím, co se dopisuje po nasazení.