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

Typická chyba je vařit pecky spolu s ovocnou dužinou „pro chuť". Chuť to nepřidá, zato se může uvolnit hořkost a džem ztmavne. Další chybou je míchání kovovou lžící v hliníkovém hrnci — kyselina reaguje s kovem a džem získá nepříjemnou pachuť. Použijte nerez nebo smalt. Také nepodceňujte sterilizaci sklenic: špatně vymyté sklenice zničí i ten nejlepší džem do týdne.

Podzimní úroda jablek často skončí v přepravkách ve sklepě a do Vánoc se polovina zkazí. Přitom stačí tři postupy a můžete mít hotové zásoby na celý rok. Jablečná šťáva, pyré a čatní se dají zvládnout i s běžným vybavením v kuchyni. Klíčové je začít včas, kdy jablka nejsou přezrálá a nezačínají hnít.

Při testování prvního API si vystačíte s nástrojem, který umí poslat požadavek s hlavičkami a tělem. Nezapomeňte nastavit Content-Type a u přijímaných dat Accept. Obojí ovlivní, zda server data správně přečte. Sledujte také čas odpovědi a velikost přenášených dat; zbytečně velké odpovědi zdržují každý požadavek a nutí klienta filtrovat data, která vůbec nepotřebuje. Pokud možno, nabídněte stránkování už od začátku, i když teď vracíte jen pár záznamů.

Na závěr si řekněme, co se vyplatí opravdu hlídat: čas odchodu, hlad a únavu. Děti se nejčastěji vztekají, když jsou vyčerpané nebo mají hlad. Pokud plánujete delší pobyt, rozdělte ho na dvě části s pauzou na svačinu. Až budete odcházet, nechte děti, ať si samy vyberou jednu věc, kterou si z parku odnesou – třeba hezký list nebo kámen. Budou se těšit na příště a vy budete mít odpoledne, které nic nestálo a přesto bylo nabité zážitky.

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.

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.

Při smažení jde především o teplotu, které olej vydrží, aniž by se rozložil. Každý tuk má jiný bod přepalu, tedy teplotu, při níž začne doutnat, hořknout a tvořit škodlivé látky. Pokud olej v pánvi kouří dřív, než do něj vložíte jídlo, je příliš horký a jeho struktura se už rozpadá. Právě proto nelze na smažení použít jakýkoli olej, který máte doma. Rozhoduje složení mastných kyselin a stupeň zpracování.

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.

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.

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.

Pro běžné smažení masa, brambor nebo zeleniny stačí dva až tři druhy olejů. Jeden vysoce stabilní na prudké smažení, jeden univerzální na restování a jeden panenský na studenou úpravu. Skladujte je odděleně, chraňte před světlem a teplem a nikdy nemíchejte dohromady. Když olej přestane vonět po surovině a začne po chemii, je čas ho vylít. Právě tento jednoduchý návyk ovlivní chuť jídla i to, kolik zbytečných látek se do těla dostane.