Zkratka proRepresentational State Transfer Application Programming InterfaceTakéRESTful API, REST rozhraní, RESTfull APIPokročilý
Definice
REST API je způsob návrhu webového rozhraní, kde klient pracuje se zdroji přes jednotné HTTP operace a server vrací jejich reprezentace, typicky ve formátu JSON. Důraz klade na jednoznačné adresy, bezstavovou komunikaci, cachování a oddělení klienta od serveru, ne na konkrétní knihovnu ani protokol navíc.
REST jako dohoda o zdrojích
REST API používá principy architektury REST pro návrh webového API. Základní myšlenka je jednoduchá: aplikace nevystavuje vzdálené funkce typu vypocitejCenu(), ale zdroje, například uživatele, objednávky nebo faktury. Klient se zdroji pracuje přes jednotné operace a server posílá reprezentaci aktuálního stavu zdroje, často jako JSON.
REST není jeden produkt, knihovna ani samostatný protokol. V praxi se nejčastěji opírá o HTTP, protože HTTP už nabízí adresy, metody, hlavičky, stavové kódy, cachování a obsahové typy. Označení RESTful se používá pro API, které se těmto principům drží důsledněji, ale hranice bývá v reálných projektech volná.
Proč jsou u REST API důležitá URL
Zdroj má mít stabilní identifikátor. Kolekce objednávek může být na /orders, konkrétní objednávka na /orders/123 a položky objednávky třeba na /orders/123/items. Dobře navržené URL nepopisuje vnitřní implementaci databáze, ale veřejný model, se kterým má klient smysluplně pracovat.
HTTP metody vyjadřují záměr požadavku. GET čte reprezentaci, POST obvykle vytváří nový podřízený zdroj nebo spouští operaci bez přirozeného identifikátoru, PUT nahrazuje známý zdroj a PATCH mění část. DELETE žádá odstranění. Stavové kódy doplňují výsledek: 200 pro úspěšné čtení, 201 pro vytvoření, 404 pro chybějící zdroj nebo 409 pro konflikt.
Co znamená bezstavovost v REST API
Bezstavovost znamená, že každý požadavek nese informace potřebné k jeho vyřízení. Server nemá spoléhat na skrytou konverzaci uloženou mezi dvěma voláními. Přihlášení se proto typicky předává tokenem v hlavičce, ne tím, že si server pamatuje poslední krok klienta. Bezstavový návrh usnadňuje škálování přes více instancí a dobře se kombinuje s load balancery.
HTTP cache může u čtecích požadavků výrazně snížit zátěž, pokud server správně používá hlavičky a identifikátory verzí reprezentace. Bezpečný provoz REST API zároveň vyžaduje HTTPS, ověřování oprávnění a často také rate limiting, aby jediný klient nevyčerpal kapacitu služby.
Kde návrh REST API bolí
Praktický návrh REST API naráží na hranice u složitých vyhledávání, dávkových operací, dlouho běžících úloh a real-time komunikace. Filtry a řazení se dají dát do query parametrů, ale příliš komplexní dotazy začnou připomínat vlastní jazyk. Dlouhé úlohy často vrací identifikátor jobu a klient se dotazuje na jeho stav.
REST API také samo neříká, jak přesně dokumentovat schéma, validovat chyby nebo verzovat kontrakt. Týmy proto často přidávají OpenAPI, jednotný formát chyb a jasná pravidla kompatibility. Kvalitní REST API je méně o hezkých URL a více o stabilním kontraktu, předvídatelném chování a dobré domluvě mezi klientem a serverem.
Příklady z praxe
Vytvoření objednávky v e-shopu
E-shop přijme objednávku přes kolekci /orders. Server vytvoří nový zdroj, vrátí stav 201 Created a v hlavičce Location pošle adresu nové objednávky, například /orders/987. Klient pak nemusí znát interní ID generátor databáze.
curl -i -X POST https://api.example.com/orders \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer eyJ...' \ -d '{"customerId":"c_42","items":[{"sku":"ABC","quantity":2}]}'Opakované čtení produktu s cache
Mobilní aplikace znovu načítá detail produktu, který už má uložený v cache. Klient pošle dříve získaný ETag a server může odpovědět 304 Not Modified bez těla odpovědi. Výsledek je rychlejší odezva a menší objem přenesených dat.
curl -i -X GET 'https://api.example.com/products/sku-123' \ -H 'Accept: application/json' \ -H 'If-None-Match: "p-123-v7"'
Časté omyly
- MýtusREST API je každé API, které běží přes HTTP.
- Ve skutečnostiHTTP samo o sobě z API nedělá REST. REST API má pracovat se zdroji, jednotnými metodami, reprezentacemi a bezstavovou komunikací. Mnoho HTTP API používá jen část těchto pravidel.
- MýtusGET může měnit data, když si to klient a server domluví.
- Ve skutečnostiGET má být bezpečná metoda pro čtení bez změny významového stavu na serveru. Porušení tohoto očekávání rozbíjí cache, prefetching, crawly i klientské knihovny, které s bezpečností metody počítají.
Časté dotazy
- Musí REST API vždy používat JSON?
- REST API nemusí vždy používat JSON, i když JSON je dnes nejběžnější formát pro webové a mobilní klienty. REST pracuje s reprezentací zdroje, takže stejný zdroj může být předán jako JSON, XML, HTML nebo jiný typ obsahu. Důležité je, aby klient a server používali srozumitelný media type, například hlavičky Content-Type a Accept, a aby reprezentace odpovídala domluvenému kontraktu.
- Kdy je REST API horší volba než WebSocket?
- REST API je slabší volba pro obousměrnou komunikaci v reálném čase, například chat, živé kurzy nebo multiplayer. REST používá model požadavek a odpověď, takže klient se musí opakovaně ptát nebo používat doplňkové techniky. WebSocket drží otevřené spojení a dovoluje serveru posílat zprávy okamžitě. REST API se ale stále hodí pro správu účtů, historii zpráv, nastavení nebo načtení počátečního stavu.
- Jak se ve REST API řeší verze?
- REST API se často verzují v URL, například /v1/orders, nebo pomocí hlaviček s media typem. Jednoduché projekty volí verzi v cestě, protože je viditelná a snadno se testuje. Větší systémy řeší hlavně kompatibilitu: přidání pole bývá bezpečné, změna významu pole nebo odstranění endpointu může rozbít klienty. Dobrá verze REST API má jasnou dobu podpory a migrační pravidla.
- Proč se u REST API tolik řeší stavové kódy?
- Stavové kódy v REST API dávají klientovi strojově čitelný signál, jak požadavek dopadl. Kód 401 říká, že chybí nebo neplatí autentizace, zatímco 403 znamená nedostatečné oprávnění. Kód 404 popisuje nenalezený zdroj a 422 se často používá pro validační chyby. Správné kódy zjednodušují retry logiku, monitoring, debugování i automatické klienty.
Zdroje
- Architecture of the World Wide Web, Volume One(otevře se v novém okně)
- HTTP Semantics(otevře se v novém okně)
- HTTP(otevře se v novém okně)
- REST(otevře se v novém okně)
Související pojmy
