Jak navrhovat REST API

Specification First

Na mých přednáškách, webinářích a školeních jsem vždy preferoval přístup Specification First. Zpočátku jsem této oblasti věnoval ve školení cca 30 % času. Postupně jsem ale školení rozšiřoval z pohledu "pravidel návrhu" a tím ukrajoval z oblasti procesu. Teď už jsem se dostal do stavu, kdy se proces do školení moc nevejde. Školení už je moc našlapané informacemi, takže nezbývá než tuto oblast zcela vypustit a trochu vzniklého prostoru využít spíše k procvičení problematiky designu. Samotný proces si totiž zaslouží mnohem více prostoru. Představuje praktický návod krok za krokem, jak vytvořit fungující návrh REST API. Proces se zde pokusím nastínit, protože samotná osnova školení tento proces kopíruje.

1. Základní analýza

K čemu bude API sloužít? Kdo ho bude používat a co s ním konkrétně bude dělat? Jak moc bude API formální a jak se postavíme k verzování? Bude to jedno univerzální API nebo více API pro různé účely? Mnoho otázek, které ovlivňují proces návrhu.

2. Volná specifikace [ Word ]

Jak jednoduše specifikovat API, aby specifikaci rozumněl skutečně každý? Pro tento účel postačuje Word, který umožňuje vytvořit specifikaci během několika málo minut. Dnes už můžeme mít docx v cloudu, takže není problém nad tím pracovat společně, komentovat a verzovat.

3. Standardizace [ OAS / Stoplight ]

Jenomže Word nelze automatizovat. Když už máme stabilní specifikaci, potřebujeme ji pokrýt standardem. A k tomu slouží oblíbená Open API Specification. Dobře navržená šablona ve Wordu zpravidla jen znamená večer strávený přepisem do formální podoby. K tomu je ideální Stoplight Studio.

4. Generování dokumentace [ Redoc ]

Máme specifikaci, která leží například na GitHubu. Jedno místo pravdy. Existuje plno JS knihoven, které tuto YAML specifikaci dokáží otočit na interaktivní HTML kód. A protože GitHub podporuje pages, můžeme mít dokumentaci vygenerovanou živě přímo na GitHubu.

5. Mockování vůči specifikaci [ Prism ]

Máme specifikaci, máme vygenerovanou dokumentaci. Frontend i backend může začít programovat. Moment. Jak může programovat něco frontend, když ještě API není nasazené? Prism je mockovací nástroj, který na základě poctivě napsané specifikace vygeneruje mock REST API. A nebojte, toto API umí vracet různé výsledky a datové sety, podle potřeb vývojářů.

6. Validace vůči produkci [ Prism ]

Napsali jsme UI proti API mocku. Teď už jen přepojit se na produkci a doufat, že vše bude fungovat. Nebude. Většinou se najde nějaký ten bug a Prism nám umožní tyto nedostatky snadno odhalit. Kromě mock serveru totiž umí spustit validační proxi a ověřovat si produkční chování vůči specifikaci.

7. Debugging API [ Postman ]

Backend vývojář má za úkol vytvořit REST API dle specifikace. A může si usnadnit život. Na základě specifikace si lze snadno nagenerovat kolekce v Postmanu a vyvíjené API jednoduše debugovat.

8. Testování a monitoring API [ Newman ]

Frontend má hotovo, backend má hotovo. Čas nasadit API na produkci. Ale funguje jak má? Postman podporuje testovací scénáře, které projdou celou kolekci krok za krokem a ověří, zda API správně funguje. Srdem této funkcionality je Newman CLI, který můžeme nasadit na build server. S každým nasazením API na vybrané prostředí tak může automaticky proběhnout test, zda API správně funguje. A produkce? Tam může tento test probíhat periodicky a sloužit jako spolehlivý monitoring dostupnosti a funkčnosti API.

Kruh se uzavřel. A to vše díky metodice Specification First. Od června 2022 si mohou firmy objednat rozšířenou verzi mého školení Design REST API. Je to dvoudenní a cenově zvýhodněná verze školení. A ti, kdo absolvovali původní školení si mohou druhý den koupit samostatně. Upravím ho tak, aby navazovalo přesně tam, kde jsme skončili.