Slovník pojmů

REST API: jak funguje architektonický styl pro HTTP rozhraní

REST není formát JSON ani hotová knihovna. Popisuje principy, podle kterých spolu komunikují klient a server.

Stručná definice

REST je konkrétní styl návrhu distribuovaného rozhraní.

REST znamená Representational State Transfer. Popisuje soubor omezení pro distribuované aplikace: oddělení klienta a serveru, jednotné rozhraní, bezstavovou komunikaci a práci s reprezentacemi zdrojů. Nestanovuje jednu knihovnu ani povinný datový formát.

Klient nepracuje přímo s databázovou tabulkou nebo vnitřním objektem serveru. Volá zdroj, například objednávku, a dostává jeho reprezentaci — často JSON. REST je užší pojem než API: API může být lokální, RPC nebo asynchronní, REST popisuje konkrétní styl webové komunikace.

Použití

Kdy REST API dává smysl

REST API se hodí pro stabilní rozhraní nad identifikovatelnými daty a stavy aplikace.

produktový katalog, zákazníci a uživatelské účty
objednávky, skladová dostupnost a administrace e-shopu
backend pro webový nebo mobilní klient
partnerské integrace se sdíleným HTTP kontraktem
exportní nebo dlouhé úlohy modelované jako samostatný zdroj

Praktický příklad

Správa objednávky a katalogu

Administrace načte objednávku přes GET /orders/4812. Fronta expedice používá GET /orders?status=paid&sort=createdAt&limit=50&cursor=… a nestahuje tak všechny objednávky najednou. Změnu adresy může provést přes PATCH /orders/4812 s předem stanoveným formátem změny.

Pokud už je objednávka odeslaná a pravidlo změnu zakazuje, API vrátí zdokumentovaný konflikt stavu, nikoli obecný úspěch. Vytvoření nové objednávky na POST /orders potřebuje navíc idempotency key: při ztrátě spojení klient neví, zda první požadavek uspěl.

Jak funguje

Zdroj, reprezentace a HTTP požadavek

Zjednodušený průběh práce s REST rozhraním:

Zdroj URL identifikuje koncept, například /orders/4812; nemusí jít o jeden řádek tabulky.
Požadavek Klient odešle metodu, URL, hlavičky a případně tělo se změnou.
Pravidla Server ověří oprávnění, vstupy i obchodní podmínky změny.
Reprezentace Odpověď vrátí HTTP status a aktuální stav zdroje nebo popis chyby.
Další stránka U kolekcí klient pokračuje podle zdokumentovaného cursoru, filtru a řazení.

Důležité vlastnosti

Sémantika, kterou klient potřebuje znát

Největší přínos RESTu není v názvu URL, ale v předvídatelném chování kontraktu.

URL a jednotné rozhraní

Kolekce může být /orders, konkrétní objednávka /orders/4812. Cílem není mechanicky zakázat každé sloveso v cestě, ale dát klientovi čitelnou sémantiku.

HTTP metody

GET čte a nemá měnit business stav. POST typicky vytváří nebo spouští zpracování. PUT nastavuje cílový stav, PATCH popisuje částečnou změnu a DELETE žádá odstranění.

Statusy a chyby

201 obvykle značí vytvořený zdroj, 202 přijatou asynchronní práci, 204 úspěch bez těla. Pro chyby je nutná konzistentní dohoda o 4xx, 5xx a formátu odpovědi.

Bezstavovost a cache

Každý požadavek nese informace nutné k pochopení. Neznamená to zákaz databáze; jde o stav komunikace. Vhodně označené odpovědi lze cachovat.

Návrh kolekcí

Stránkování, filtry, řazení a změny

Seznam objednávek může růst bez omezení. Kontrakt musí říct, jak získat pouze relevantní a další výsledky.

Filtrování: Například status=paid musí mít jednoznačný význam a validaci povolených hodnot.
Řazení: Stabilní řazení je důležité pro návaznost stránek, zvlášť při souběžných změnách dat.
Cursor: Cursor často lépe zvládá velká nebo proměnlivá data než pouhý offset; jeho tvar je součástí kontraktu.
Verzování a OpenAPI: REST neurčuje místo verze. OpenAPI může popsat cesty, parametry a odpovědi, samo o sobě však z API REST nedělá.

Výhody a omezení

REST není šablona pro každou business akci

Přínosy

využívá známé HTTP metody, statusy, hlavičky a nástroje
konzistentní zdroje a metody snižují počet výjimek pro klienta
odděluje klienta a server a umožňuje více typů klientů
bezstavové požadavky usnadňují opakování a horizontální provoz

Časté chyby

GET použitý pro změnu stavu
vždy HTTP 200 a neurčitý text success v JSONu
rušení starých polí bez období kompatibility
stateless vykládané jako zákaz přihlášení nebo databáze

Hranice použití

Ne každé JSON API je skutečně RESTful.

API s POST /doSomething a vždy stejným statusem může fungovat, ale nevyužívá dobře HTTP sémantiku. Opačná chyba je vytvářet nepřirozené URL jen kvůli nálepce REST. U dlouhé operace je často čitelnější vytvořit zdroj úlohy a vrátit 202, než předstírat okamžité dokončení.

Idempotentní HTTP metoda sama neřeší duplicitu business operace, která zasahuje více systémů. Při vytvoření objednávky nebo zásilky je potřeba navrhnout ochranu na úrovni konkrétní operace.

Na co myslet

Pravidla pro čitelné HTTP rozhraní

Kontrakt by měl popsat i výjimečné a provozní stavy, ne jen šťastnou cestu.

GET bez mutace business stavu
jednoznačné statusy, strojový typ chyby a korelační ID
maximální limit a stabilní řazení kolekcí
zpětně kompatibilní změny nebo jasný plán migrace
bezpečné předávání tokenů mimo query string

Časté otázky

Co znamená REST v praxi

Je REST API a HTTP API totéž?

Ne. HTTP API může používat HTTP bez dodržení REST omezení. REST je jeden architektonický styl s jednotným rozhraním, zdroji a dalšími principy.

Je každé API s JSONem REST?

Ne. JSON je datový formát. O RESTu rozhoduje sémantika zdrojů, metod, stavů a komunikace, ne koncovka odpovědi.

Jaký je rozdíl mezi PUT a PATCH?

PUT nastavuje reprezentaci cílového zdroje, PATCH popisuje částečnou změnu. Kontrakt PATCH musí přesně určit, jak se změna interpretuje; idempotence PATCH není automatická.

Musí REST API verzovat URL?

Ne. REST neurčuje umístění verze. Důležitější je vyhnout se nekompatibilním změnám a předem popsat přechod.

Jak REST API používám v praxi

API navrhuji s ohledem na provoz integrace.

U integračních služeb řeším vedle endpointů také datové kontrakty, chybové stavy, opakování požadavků a dohledatelnost synchronizací.

Jak pracuji s API a integracemi Nezávazně probrat projekt