Stopařův průvodce REST API

Ostatní 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.

Úrovně REST

Úrovně REST

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/com­ments - vrátí komentáře k článku s ID 1
  • GET /articles/1/com­ments/5 - vrátí komentář s ID 5 k článku s ID 1
  • DELETE /articles/1/com­ments/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ů.


 

  Aktivity (1)

Článek pro vás napsal Drahomír Hanák
Avatar
Autor v současné době studuje Informatiku. Zajímá se o programování, matematiku a grafiku.

Jak se ti líbí článek?
Celkem (12 hlasů) :
4.916674.916674.916674.916674.91667


 


Miniatura
Předchozí článek
Iluze prostoru
Miniatura
Všechny články v sekci
Články nejen o programování

 

 

Komentáře

Avatar
David Čápka
Tým ITnetwork
Avatar
David Čápka:

Pěkný článek. Určitě sem časem přidám ten náš curl wrapper v PHP.

Odpovědět  +1 17.11.2013 11:12
Miluji svou práci a zdejší komunitu, baví mě se rozvíjet, děkuji každému členovi za to, že zde působí.
Děláme co je v našich silách, aby byly zdejší diskuze co nejkvalitnější. Proto do nich také mohou přispívat pouze registrovaní členové. Pro zapojení do diskuze se přihlas. Pokud ještě nemáš účet, zaregistruj se, je to zdarma.

Zobrazeno 1 zpráv z 1.