Hlavní navigace

Jak na čistý REST návrh

Obálka je jeden z nejčastějších hříchů vůči čistému REST návrhu. Přečtěte si, proč a jak se ho vyvarovat.

Doba čtení: 3 minuty

Internet je plný zajímavých článků o tom, jak používat HTTP a JSON a navrhovat REST rozhraní tak, aby práce se zdroji, které reprezentují, byla nejen snadná a logická, ale i příjemná. Hned na úvod bych rád uvedl své nejoblíbenější zdroje, které jsou z mého pohledu „must read“, pokud chcete REST rozhraní (s citem) navrhovat.

Vřele doporučuji pročíst od začátku až do konce, protože mně osobně dávají smysl a téměř ve všech bodech s nimi souhlasím. Ono ani není divu, protože pokud si vygooglujete frázi „REST API best practices design, tak se vám zobrazí na první stránce ve výsledcích vyhledávání a nějakou dobu tam snad i vydrží.

Ve své praxi jsem se bohužel setkal i s méně kvalitním designem REST API, který jsem jako Java vývojář musel buď zpracovávat, nebo (ještě hůře) spravovat a rozvíjet. Rád bych proto uvedl několik příkladů a důvodů, proč je nepoužívat. Jako zastánce KISS principui když ne vždy se mi jej daří dodržovat mám prostě jednoduchost rád.

Bez obalu

Obálka je nejčastější prohřešek vůči čistému návrhu REST rozhraní. Setkal jsem se s ní mnohokrát a pokaždé k tomu měl autor dobré důvody. Hlavní důvod, proč se tomuto vyhýbat, je to, že mi prostě obalovací atribut sémanticky k reprezentaci zdroje nesedí a nemá tam co dělat. Například na dotaz `GET /clients/1` namísto:

raději použiju:

To samé platí i pro zdroje typu kolekce. Čili místo:

postačí prosté:

A nebojte se, frontend nebo jiný HTTP klient si s JSONArray na začátku obsahu poradí velmi dobře.

Další příklad neopodstatněné obálky je generická odpověď se status kódem a vlastním výsledkem:


Někdo by mohl argumentovat tím, že se pak podobným způsobem dají popsat i chyby, a tím pádem se JSON dá dobře zpracovávat:

Ano, ale chyba není reprezentací zdroje, to je prostě jen výjimečný stav, který při práci se vzdálenými zdroji může bohužel nastat a my s ním musíme počítat a správně s ním i zacházet.

K signalizaci chyb a výjimečných stavů se v HTTP používají 4×x a 5×x status kódy a jejich zpracování by mělo být oddělené od zpracování zdroje (v Javě například error handlerem).

Dalším důvodem, proč generické obálky nepoužívat, je to, že objekty v nich se hůře zpracovávají a při deserializaci se musí nejprve vybalit a ideálně i zkontrolovat, zda vůbec nějaký objekt v obálce máme (nullita). Můžeme sice pro každý objekt vydefinovat (generický) wrapper a použít Java validace, ale podle mého názoru je to zbytečná práce a overhead. 

Nakonec je i HTTP odpověď (čili data na drátě) nepatrně kratší.

Doufám, že se vám článek líbil a inspiroval vás k další práci s REST API rozhraním. Účastnit se jeho návrhu, implementace a testování můžete i u nás v Creative Docku. Pro nové fintechové projekty zrovna hledáme vývojáře, co se nebojí zkoušet nové technologie, porušovat pravidla a inovovat evropský trh. Tak se přidejte!

O autorovi

Josef Boukal

Pepa má dlouholeté zkušenosti s vývojem serverových Java aplikací postavených převážně na Spring Frameworku. Preferuje jednoduché a čisté návrhy. V praxi si vyzkoušel i Fullstack Development včetně testování, trošku i DevOps, ale nejvíce ho to stejně táhne k návrhu a implementaci serverových částí a věcí behind the scenes. Vyzkoušel si i projektové řízení a jeho oblíbenou metodikou je agile, i když nejvíce věří v to, že dobrý projekt dělají dobří lidé, a nikoli metodika.Aktuálně pracuje v Creative Dock na novém fintech projektu pro jednu finanční instituci, kde má na starosti vývoj backendové části postavené na Spring Boot technologii.