Chapter 01: Introduction

Jsou tomu více než dvě dekády od nástupu éry Web 2.0, která s sebou přinesla zásadní rozvoj webových služeb. Svět byl na počátku druhého tisíciletí vybaven mnoha webovými standardy, které vznikly v reakci na velký zájem o veřejný internet. S nástupem interaktivních webových aplikací a rozvojem JavaScriptu rostl tlak na vznik jednoduchých a flexibilních webových služeb. Jako přirozená odpověď na tuto potřebu se postupně prosadila REST API.

Přestože jsou principy RESTu známé více než dvacet let, mezi vývojáři stále panuje nejednotný pohled na to, jak by správně navržené REST API mělo vypadat.

Mé první zkušenosti s návrhem REST API jsem začal sbírat v roce 2015. První projekt jsem se snažil uchopit co nejpřísněji s ohledem na tehdejší standardy a konvence. Přestože jsem měl k dispozici nespočet materiálů, většina si v mnoha klíčových oblastech odporovala. Teprve praxí jsem měl možnost najít vlastní cestu k funkčnímu designu REST API. V roce 2019 jsem se stal nezávislým profesionálem na volné noze. Do portfolia mých služeb vždy neodmyslitelně patřila firemní školení. Po několika iteracích technologického školení Vývoje REST API jsem si uvědomil, že povědomí o návrhu REST API je v České velmi špatné a ještě ten samý rok jsem do mého portfolia kurzů přidal školení Design REST API.

Od roku 2000 toto školení soustavně vylepšuji na základě zpětné vazby od účastníků kurzu. Jedná se o školení s velkou mírou interaktivity. Obsahuje mnoho kontroverzních oblastí, které se rozcházejí s představou vývojářů o návrhu webových služeb. Kromě standardů dnešní REST API do značné míry vycházejí z konvencí. 

Uvažovat nad designem API je nutné v širším kontextu. Jedině tak lze navrhnout webovou službu postavenou na pravidlech, která jsou ve vzájemné synergii a neodporují si. 

Abych tuto oblast zpřístupnil nejen firmám, ale i jednotlivcům, rozhodl jsem se sepsat všechny poznatky z návrhu REST API do průvodce, kterého právě čtete. V tomto průvodci najdete mé know-how, které vám zaručeně pomůže navrhovat REST služby, na které budete hrdí. Uvést tohoto průvodce k životu mi trvalo několik stovek hodin a najdete v něm zkušenosti sesbírané z mnoha projektů za posledních 10 let. Na začátku roku 2025 jsem původní český obsah kompletně revidoval a přepsal do angličtiny i pro zbytek světa.

Jak číst tohoto průvodce?

Obsah jsem sepsal tak, aby na sebe jednotlivé kapitoly navazovaly. Doporučuji proto zejména prvních 17 kapitol přečíst poctivě po sobě. Poslední kapitoly průvodce jsou již tématická rozšíření. Přímo v průvodci občas najdete odkaz na doplňující článek, který se určitým tématům více věnuje do hloubky.

Přestože bylo mou snahou v průvodci popisovat především dobrou praxi, rozhodl jsem se u některých témat popsat i ta špatná řešení. Proto na některých místech narazíte na barevné značky, které popisují:

🟢 doporučené řešení, dobrá praxe
🟠 akceptovatelné řešení s výhradou
🔴 nedoporučené řešení, špatná praxe

Východiska

Pokládám za důležité zdůraznit, že tento průvodce dodržuje veškeré uznávané standardy. V mnoha případech jsou má doporučení přísnější, protože standardy jsou s ohledem na zpětnou kompatibilitu často benevolentní. Nakonec konvence v tomto průvodci vychází nejen z mé praxe, ale i z osvědčených řešení z mnoha moderních API, které jsem jako vývojář implementoval. Právě role integrující strany mi umožnila identifikovat mnoho míst, ve kterých design API často selhává.

Věřím, že tuto autorskou práci oceníte a přeji vám inspirativní čtení.

Miroslav Holec
Your API Design Guide