První REST API: chyba v odpovědi, která rozbije klienta

První vlastní REST API vzniká většinou jako jednoduchý endpoint, který vrátí data z databáze. Jenže právě tady se láme úspěch: klient, ať už prohlížeč, mobil nebo jiná služba, se rozhoduje podle toho, co mu server pošle zpět. Pokud odpověď nemá jasnou strukturu, každý další požadavek přinese jiný problém. Začni tím, že si před psaním kódu sepíšeš, co přesně má API vracet: jaká data, v jakém tvaru a co se stane, když data nejsou.

Kdy začít a co udělat nejdř�

Před nasazením si napiš několik ručních požadavků a projdi je proti běžícímu serveru. Zkontroluj, co se stane při chybějícím parametru, při neplatném JSON, při příliš dlouhém vstupu a při neexistujícím ID. Právě tyto situace odhalí, že validace chybí nebo že chybová odpověď obsahuje celý stack trace. Do produkce nikdy neposílej interní výjimky. Zaznamenej je do logu a klientovi vrať obecnou zprávu s kódem.

U věšáku rozhoduje hloubka, ne šířka. Stěnový věšák s hloubkou 25–30 cm udrží kabát i bundu, aniž by ramena trčela do průchodu. Pokud je chodba opravdu těsná, použijte výklopné háky, které se sklopí ke zdi, nebo lištu s háky nad sebou ve dvou úrovních. Horní řada pro dospělé, spodní pro děti. Počítejte jeden hák na osobu plus dva na hosty. Víc háků svádí k věšení tašek a šál, které pak visí přes sebe a tvoří hromadu.

Stavové kódy nejsou dekorace Nejčastější chyba začátečníků je vracet vždy HTTP 200 a do těla napsat {"error": "něco se pokazilo"}. Tím zabiješ možnost klienta rozlišit úspěch od selhání. Pro úspěšné vytvoření použij 201, pro prázdnou odpověď 204, pro neplatný vstup 400, pro chybějící oprávnění 401 nebo 403, pro nenalezený záznam 404 a pro neočekávanou chybu serveru 500. Tělo odpovědi drž konzistentní: při úspěchu vracej data, při chybě objekt s polem pro kód a lidsky čitelnou zprávu. Klient pak může reagovat podle stavového kódu, aniž by musel luštit text.

Jakmile API funguje, zdokumentuj každý endpoint: metodu, cestu, očekávané parametry, ukázku požadavku a ukázku odpovědi včetně chybových stavů. Dokumentace není formalita, ale nástroj, díky kterému klient napsaný za měsíc nebude muset hádat, co jsi tím myslel. První REST API se láme na maličkostech: chybějící hlavičce, nejasném stavovém kódu a nekonzistentním tvaru odpovědi. Když tyto tři věci podržíš, zbytek se skládá mnohem snáz.

Pozor na typické chyby. První je podestýlka z jemného prachu, který se slepí do tvrdé krusty. Druhá je sláma, která se rychle rozmočí a plesniví. Třetí je holá podlaha s občasným podsypáním — to je pro nohy nejhorší. Čtvrtou chybou je přeplněný kurník: čím víc slepic na malém prostoru, tím rychleji se podestýlka zamačká a provlhne. Počítejte s dostatkem místa na hřadování i na pohyb.

Požadavek začíná metodou a cestou. Pro čtení používej GET, pro vytvoření POST, pro úpravu PUT nebo PATCH a pro smazání DELETE. Cesta má být podstatné jméno v množném čísle, například /uzivatele, ne sloveso. Parametry filtrování dávej do query stringu, identifikátor konkrétního záznamu do cesty. Tělo požadavku posílej jako JSON a v hlavičce vždy uveď Content-Type: application/json. Bez této hlavičky server často data vůbec nepřečte a vrátí chybu, která vypadá nesmyslně.

Když už slepice kulhá, prohlédněte chodidla. Najdete-li zarudlé, teplé a oteklé místo, izolujte ji na suché, měkké podestýlce a ránu vyčistěte. Pokud se objeví hnis nebo zápach, patří pták k veterináři. Většina případů se ale dá zvládnout včasným zásahem: suchý podklad, měkký materiál a čistota. Sledujte, jak slepice stojí a chodí. Když začne našlapovat opatrně nebo se vyhýbá hřadu, je to signál, že podestýlka potřebuje výměnu, ne odklad.

Základem je správná vrstva podestýlky. Podlahu nejdřív vysypte tenkou vrstvou savého materiálu, který pohltí vlhkost, a teprve na něj dejte hlavní vrstvu. Ta má být vysoká alespoň pět centimetrů, u větších plemen i více. Příliš tenká vrstva se rychle promáčkne až na tvrdý povrch a slepice pak stojí vlastně na betonu nebo na dřevě. Naopak příliš vysoká a sypká vrstva se rozhrabává a odkrývá spodní mokrou část.

Odpověď by měla být předvídatelná. Pokud vracíš seznam, obal ho objektem s polem položek a počtem, ne holým polem. U jedné položky vracej objekt, ne jeden prvek z pole. Datum posílej v jednotném formátu, ideálně ISO 8601. Čísla neposílej jako řetězce, pokud to není nutné. Prázdné hodnoty řeš konzistentně: buď null, nebo pole vynech, ale v celém API stejně. Klient, který jednou dostane null a podruhé prázdný řetězec, bude mít v kódu zmatek.

Typická chyba je nakupovat úložné boxy dřív, než víte, co v domácnosti zůstane. Další chybou je rušení věcí po rodinných příslušnících bez domluvy. U společných prostor se vždy nejdřív zeptejte, co komu vadí. U svých věcí rozhodujte sami. Pozor také na pravidlo „možná se to bude hodit". To platí jen pro sezónní věci, které skutečně používáte každý rok. U zbytku je „možná" jen výmluva.