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ží.
- Best Practices for Designing a Pragmatic RESTful API
- RESTful API Designing guidelines — The best practices
- API Design na webu Microsoft Azure
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 principu– i 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.
ČLÁNKY DO MAILU