První REST API: chyba, která zdrží každý testovací požadavek

Nové Město pražské není jen Václavské náměstí a Národní třída. Stačí sejít o ulici dál a narazíte na souvislou vrstvu funkcionalistické architektury z let 1920–1940. Problém je, že většina lidí ji vnímá jako kulisu k nákupům, a tak jim uniká. Základ je jednoduchý: vyhraďte si dvě hodiny, vezměte si pohodlné boty a jděte pěšky. Funkcionalismus se totiž čte z detailů, ne z průčelí.

Poslední a nejčastější past je dokumentace. Bez ní si za měsíc nebudete pamatovat, proč určitá cesta vrací jiný tvar dat. Sepište ke každému zdroji metody, povinné parametry a příklady odpovědí včetně chybových stavů. Až budete API rozšiřovat, budete rádi, že jste začali ujasněním zdroje, metod a jednotného formátu odpovědí. Právě tyto tři věci rozhodují o tom, jestli první REST API zůstane použitelné, nebo skončí jako sbírka výjimek.

Vařte v širokém hrnci, aby se voda rychleji odpařovala. Ovoce nejprve rozvařte doměkka, pak přidejte cukr. Na kilogram ovoce použijte 400–500 g cukru; méně cukru znamená delší var a větší riziko, že džem zhnědne. Míchejte často, hlavně u dna. Var trvá 20–40 minut. Zkouška na talířku: kápněte trochu džemu na studený talíř, nechte chvíli zchladnout a přejeďte prstem. Pokud se vytvoří vráska, je hotovo.

Co sundat a co nech

Teplotu regulujte postupně. Začněte na 60 °C a po 10 minutách přidejte. Nikdy nenechávejte těleso bez dozoru. Před každým použitím zkontrolujte, zda v místnosti nejsou hořlavé předměty – ručníky, noviny, plastové lahve. Vlhko vzniká politím kamenů vodou, ale pozor: příliš mnoho vody najednou může způsobit prskání a opaření. Do hrnce s vodou přidejte pár kapek éterického oleje, jen pokud víte, že vám nevadí. Po saunování vždy vyvětrejte a otřete podlahu, aby se do zdiva nevsákla vlhkost.

Druhá ruka často trpí na vytahané lemy, prodřené lokty nebo utržené knoflíky. Tyto vady se dají opravit dřív, než se rozpadne celý kus. Knoflík přišijte hned, jakmile povolí nit. Drobnou dírku na švu zajistěte stehem, dokud se netrhne dál. Zip namažte voskem nebo grafitem z tužky, pokud jde ztuha. Prádlo, které už nedrží tvar, nepřetahujte přes ramínka – skladujte ho volně složené. Věšáky na pleteniny jsou špatný nápad, ramena se vytáhnou a materiál ztratí pružnost.

První vlastní REST API obvykle vzniká v okamžiku, kdy potřebujete, aby se data z jedné aplikace dostala do druhé. Teorie je jasná: klient pošle požadavek, server vrátí odpověď. V praxi se ale rozhoduje o úspěchu mnohem dřív, než napíšete první řádek logiky. Než začnete řešit databázi, musíte mít jasno v tom, co je zdroj, jak se jmenuje a jaké operace nad ním budou klienti provádět. Právě tady vzniká nejvíc zbytečných oprav, protože se mění názvy cest i struktura odpovědí za pochodu.

U chybových odpovědí se vyplatí vrátit strojově čitelný kód a k němu krátké vysvětlení. Vyhněte se výpisům celých interních chyb, které prozrazují strukturu databáze nebo cesty na serveru. Zároveň ale neposílejte prázdné tělo, ze kterého se nedá poznat, co se pokazilo. U validačních chyb je užitečné uvést, které pole selhalo a proč. Tím ušetříte hodiny ladění na straně klienta i na straně serveru.

Základním kamenem je správně zvolená cesta a metoda. Zdroj pojmenujte podstatným jménem v množném čísle, nikdy ne slovesem. Adresa jako /getUsers nebo /user/delete je častá chyba, která se později těžko předělává. Metoda GET čte, POST vytváří, PUT nebo PATCH upravuje a DELETE maže. Pokud metodu zvolíte špatně, narazíte na problémy s cache, s proxy servery i s tím, jak API vnímají nástroje pro testování. Držte se také pravidla, že GET nesmí nic měnit.

Další častá chyba je spěch. Funkcionalistické domy mají často průchozí dvory a pasáže, které nejsou na první pohled vidět. Projděte jimi. Právě v nich najdete původní zábradlí, dlažbu nebo schodišťová okna. Někdy stačí projít vraty do dvora a ocitnete se v jiné době. Nebojte se, že se dostanete někam, kam se nemá – pokud nejste za soukromými dveřmi, dvory jsou běžně průchozí.

Poslední praktická rada: jděte dvakrát. Jednou dopoledne, kdy světlo zvýrazní plasticity fasád, a jednou za soumraku, kdy vynikne osvětlení oken a vstupů. Funkcionalisté navrhovali domy pro oba režimy. Kdo projde Nové Město jen jednou a za pochodu, uvidí jen šedé kostky. Kdo se zastaví, najde vrstvu, která se od Emy Destinnové k palácům táhne jako souvislý příběh.

Formát odpovědi rozhoduje o tom, jak snadno se API používá Odpověď by měla být konzistentní. Když jednou vrátíte data přímo v těle odpovědi a jindy je zabalíte do dalšího objektu, klient se v tom ztratí. Zvolte jednotný formát a dodržte ho u všech stavových kódů. Stavový kód není kosmetická záležitost: 200 znamená úspěch, 201 vznik zdroje, 400 chybu na straně klienta, 404 nenalezeno a 500 chybu serveru. Velmi častá chyba je vracet 200 i u chyby a schovávat problém do těla odpovědi. Klient pak nemá šanci rozlišit úspěch od selhání, aniž by parsoval text.