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