Stopařův průvodce REST API
Už jste někdy potřebovali přistupovat k datům aplikace z více prostředí nebo svá data poskytovat i dalším uživatelům? Pokud ano, nejspíš jste také museli definovat nějaké veřejné rozhraní (API), kterému by rozuměly všechny vaše aplikace a případně další konzumenti vašich dat. REST toto API definuje za vás. Je to rozhraní pro distribuované prostředí orientované na data, nikoli na volání procedur jako např. RPC (XML-RPC) či SOAP.
REST má samozřejmě svá specifika a (dost často nepsané) standardy, které je ale vhodné dodržovat. Abychom je lépe pochopili, rozdělíme si REST do 4 úrovní tak, jak je rozdělil Leonard Richardson.
Nultá úroveň
Jedná se o samotný přenos dat. REST se totiž neváže na HTTP, takže je teoreticky možné použít jinou metodu přenosu. HTTP je ale dnes tak rozšířený protokol, že snad ani nemá cenu mluvit o jiných možnostech. Navíc za nás vyřeší spoustu věcí, a tak můžeme rovnou skočit na další bod.
První úroveň - zdroje (Resources)
Místo toho, aby se všechny požadavky posílaly na jeden centrální bod,
použije se jich více. Každý zdroj (resource) má pak právě
jeden koncový bod, kde ho lze dosáhnout. Např.
GET /articles - vrátí seznam článků,
GET /articles/1/comments vrátí seznam komentářů k jednomu
danému článku apod. Je důležité zvolit si nějaký standard
pojmenovávání zdrojů (třeba používat buď jen množné číslo -
GET /articles, GET /comments, nebo jen jednotné
GET /article, /comment)
Druhá úroveň - HTTP Verbs
V protokolu HTTP je asi nejznámější metoda GET. Byla by ale chyba omezovat se při návrhu API jen na ni. Protokol HTTP jich totiž nabízí mnohem více. Jsou to: PUT, PATCH, DELETE, OPTIONS a další. Samotné názvy zdrojů neobsahují slovesa, jen podstatná jména. Akci, kterou chceme provést, vyjádříme právě pomocí HTTP Verbs.
Významy jednotlivých HTTP Verbs jsou následující:
- GET - získání dat
- POST - vytvoření
- PUT - úpravy (upraví celý zdroj - chová se jako SET)
- DELETE - smazání
- PATCH - částečné úpravy
Metodu PATCH přitom v originální specifikaci HTTP nenajdeme. Ale jelikož je HTTP rozšiřitelný protokol, časem začaly vznikat nová užitečná rozšíření. Používáním metody PATCH snížíme tok informací po sítí, protože přenášíme jen data, která se změnila, kdežto u PUT přenášíme vždy celý zdroj.
Stavové kódy
V http také najdeme stavové kódy a je jich zdaleka víc než jen 200 OK. Poměrně známý je ještě kód 404 Not Found (nenalezeno). Pro nás vývojáře pravděpodobně ještě 500 Server Error. V REST API jsou nejčastěji používané:
- 200 OK - požadavek proběhl v pořádku
- 201 Created - při POST, pokud byl vytvořen nový obsah
- 204 No Content - když požadavek na server proběhne v pořádku, ale server nic nevrátí
- 304 No Modified - pokud nebyl od posledního požadavku nebyl změněn obsah – používá se pro nativní http cache
- 400 Bad Request - požadavek na server je nějakým způsoben nečitelný (třeba špatný JSON apod.)
- 401 Unauthorized - klient není ověřen
- 403 Forbidden - klient nemá přístup k danému obsahu
- 404 Nod Found - zdroj není nalezen
- 405 Method Not Allowed - zdroj není dostupný pro tuto metodu. Například je možné použít GET /articles a POST /articles, ale už třeba nemůžeme článek smazat. Nelze tedy zavolat DELETE /articles - je vhodné uživatelům našeho API v tomto momentu poskytnout seznam podporovaných metod pro danou URL
- 410 Gone - zdroj není už na téhle adrese dostupný - to se používá při verzování
- 415 Unsupported Media Type - klient v požadavku na server uvedl hlavičku Content-Type, kterou server nepodporuje
- 422 Unprocessable Entity - chyba validace dat - třeba formuláře apod.
- 429 Too-Many Requests - pokud klient překročil maximální počet požadavků, třeba za den
Nezapomeňte, že je HTTP rozšiřitelný protokol. Ve specifických případech tak můžeme použít vlastní stavový kód, pokud bude zachována hlavní třída (tj. odpověď: 1xx - informační, 2xx - úspěšná, 3xx - přesměrování, 4xx - chyba klienta, 5xx - chyba serveru)
Velice důležité je udržet REST API bezstavové. To znamená, že by např. ověření uživatele nemělo záviset na session nebo cookies. Každý požadavek by měl obsahovat ověřovací údaje, podle kterých REST API pozná, kdo se připojil. Možností, jak takové ověření provést, je víc. Nejrozšířenějším standardem je OAuth. Počítá i s případy, kdy nelze u klienta jako je Android nebo JavaScript uchránit citlivé údaje.
Třetí úroveň – Hypermedia Controls
Poslední třetí úroveň je známá pod akronymem HATEOAS (Hypertext as the Engine of Application State). Zjednodušeně jde o to, že známe pouze základní koncový bod, který vrací spolu s daty také odkazy na další zdroje, ty zase na další a tak dále. Každý zdroj tak klientovi dává možnosti, jakou akci může provést nebo co dál udělat. Představit si to můžeme jako HTML dokument s odkazy na další stránky. Výhody jsou zřejmé – klient není závislý na URL adresách (musí znát pouze tu první, dál jen „kliká“ na odkazy), ty se mohou klidně za běhu měnit. Dále lze přidávat nebo měnit další funkčnost, aniž by bylo potřeba cokoli změnit u klienta.
Přestože sami autoři REST tvrdí, že REST API musí být řízené odkazy, zatím se HATEOAS moc nepoužívá. V současné době totiž není moc dostupných nástrojů a materiálů pro HATEOAS.
Implementace REST API
GZIP komprese
Kompresí zdrojů můžeme ušetřit až 80 % velikosti zdroje, čím se sníží přenos dat po síti.
JSON jako hlavní formát
JSON je dnes hodně rozšířený formát, se kterým umí dobře pracovat
spousta jazyků. Pokud by ale bylo nutné podporovat i jiný formát, použijeme
hlavičku Content-Type pro detekci. Př.: když klient pošle
požadavek s Content-Type: application/json vrátíme mu JSON,
když Content-Type: application/xml, vrátíme XML - když něco
jiného, vrátíme klientovi error 415 Unsupported Media Type. Detekci typu
můžeme dát i do URL (GET /articles.xml,
GET /articles.json), ale v tom případě je vhodné hlavičku
Content-Type úplně ignorovat. Použití HTTP hlavičky je "čistší"
řešení.
Cache
HTTP má vestavěnou podporu pro nesdílený cache pomocí hlaviček ETag nebo Last-Modified.
Relace
Osvědčilo se mi používat URL typu
/<zdroj>/<id>/<relace>/<id relace>/<další relace>
atd. Pro úplnost uvedu pár příkladů:
- GET /articles/1/comments - vrátí komentáře k článku s ID 1
- GET /articles/1/comments/5 - vrátí komentář s ID 5 k článku s ID 1
- DELETE /articles/1/comments/5 - smaže komentář s ID 5 u článku s ID 1
Stránkování
Není nic jednoduššího než klientovi poskytnout URL na další,
předchozí, příp. poslední stránku. Používá se na to hlavička
Link. Je taky vhodné klientovi vrátit přesný počet všech
položek v hlavičce X-Total-Count
snake_case, camelCase, PascalCase
Je vhodné používat jednotnou konvenci pro všechny zdroje nebo ještě
lépe nabídnout klientům možnost, použít konvenci jinou.
snake_case je mnohem líp čitelný než camelCase,
ale s camelCase se zase přirozeněji pracuje v JS.
Vývoj REST API
Pro návrh API a jeho mockování existuje velice užitečný nástroj Apiary.io Díky němu lze poměrně snadno navrhnout prototyp REST API, který pak následně můžeme použít jako zástupce serveru. To umožňuje zaměřit se víc na vývoj samotné aplikace a skvěle oddělí vývoj její klientské a serverové části.
Testování
Skvělým nástrojem pro testování může být třeba cURL. Jednoduchý konzolový nástroj, který umožňuje volat HTTP požadavky. Pokud máte radši GUI, podívejte se na rozšíření do vašeho prohlížeče. Do Chrome například existuje skvělé rozšíření Postman a do Firefoxu najdete spoustu addonů.
Hotová řešení
Za zmínku stojí také databáze CouchDB, ve které se na data dotazujeme právě pomocí REST API. Svoje REST API má i například ElasticSearch a spousta dalších.
Závěr
REST je architektura API, která nám umožňuje přistupovat k datům a provádět nad nimi CRUD operace. REST je bezstavový, čímž jednak značně zjednodušuje komunikaci s API a umožňuje paralelní zpracování obsahu. Zároveň ho lze dost snadno použít s HTTP, což je velice rozšířený protokol (v podstatě dnes nemá smysl používat jiný). V neposlední řadě nám poskytuje určitý standard, takže není problém použít cizí API nebo naopak nabízet vlastní velkému množství dalších uživatelů.
