Věcný obsah, základní pojmy - Web API

REST je architekturou rozhraní, která je navržená pro distribuované prostředí. Na rozdíl od známých XML-RPC nebo SOAP je REST orientován datově a nikoliv procedurálně. Stav aplikace a chování je vyjádřen takzvaným zdrojem (resource), každý zdroj musí mít unikátní identifikátor URL. REST podporuje čtyři základní metody, které jsou známé pod označením CRUD, tedy vytvoření dat (Create), získání požadovaných dat (Retrieve), změnu (Update) a smazání (Delete). Tyto metody jsou implementovány pomocí odpovídajících metod HTTP protokolu.

Požadavky kladené na architektonický styl vyhovující paradigmatu REST:

• Oddělený klient-server - Při návrhu REST API musí být klientské a serverové aplikace na sobě zcela nezávislé. Jedinou informací, kterou by klientská aplikace měla znát, je URI požadovaného zdroje.
• Bezestavovost - Každý požadavek musí obsahovat všechny informace nezbytné pro jeho zpracování. REST API nevyžadují žádné relace na straně serveru. Serverové aplikace nesmějí ukládat žádná data související s požadavkem klienta.
• Ukládání do mezipaměti - Je-li to možné, měly by být prostředky kešovatelné na straně klienta nebo serveru. Odpovědi serveru také musí obsahovat informace o tom, zda je pro dodaný zdroj povoleno ukládání do mezipaměti. Cílem je zlepšit výkon na straně klienta a zároveň zvýšit škálovatelnost na straně serveru.
• Jednotné rozhraní - Všechny požadavky API na stejný zdroj by měly vypadat stejně, bez ohledu na to, odkud požadavek pochází.
• Vícevrstvý systém - V REST API procházejí volání a odpovědi různými vrstvami. Obecně platí, že se klientské a serverové aplikace nepřipojují přímo k sobě. V komunikační smyčce může být řada různých prostředníků. Rozhraní REST API musí být navrženo tak, aby klient ani server nebyli ovlivněni tím, zda komunikují s koncovou aplikací nebo prostředníkem.

HTTP je komunikační protokol, který se využívá pro komunikaci webového serveru s klientským softwarem. HTTP je založený na zasílání požadavků a odpovědí na ně. Klient provede HTTP požadavek (request) a webový server mu na něj odpoví pomocí HTTP odpovědí (response).

Adresa URL rozhraní API je strukturována podobně jako „běžná“ adresa URL webových stránek, ale konvence pojmenování jsou trochu jiné a obvykle dodržují přísnější organizační logiku.

Adresa URL v API má obvykle 5 části:

• Základní URL – je počáteční částí adresy URL rozhraní API. Skládá se z protokolu, hostu a portu. Např.: http://localhost:80
• Jméno spojení - část URL určující nad jakým DB spojením má server požadavek provést. Např.: /develop
• Kontroler - organizační celek, typicky název BO v množném čísle. Např.: /storecards

• Koncový bod (endpoint) - identifikuje, ke kterému zdroji chce klient přistupovat. Např.: /{id}.

  Pokud provádíte dotaz nad konkrétním BO, potom použijte endpoint, např: /{id}/confirm, a nepředávejte id jako query parametr ani v těle dotazu.

• Query string – skládá se z query parametrů, které slouží k doplnění API dotazu o dodatečné informace ovlivňující jeho zpracování. Např.: ?executor=outprocess

Úplná adresa URL rozhraní API spojí tyto segmenty do adresy URL:

http://localhost:80/develop/storecards/{id}?executor=outprocess

Query string

Parametry se zapisují tak, že za adresou následuje otazník a za ním zapsané páry ve formátu klíč=hodnota. Páry jsou odděleny znakem &. V případě pravdivostního parametru, pokud je uveden jako poslední parametr v query stringu, není třeba uvádět hodnotu a bere se jako by byla použita hodnota True.

Query string primárně neslouží k přenosu dat, ale metadat, nepoužívejte jej například pro předání seznamu ID, to patří do těla, neboť zde neprobíhá komprese a URl má jen omezenou délku.

Kódování URL

Rezervované znaky mají v URL zvláštní význam a pokud mají být použity mimo jejich vyhrazený význam, musí být zakódovány.

Query string primárně neslouží k přenosu dat, ale metadat, nepoužívejte jej například pro předání seznamu ID, to patří do těla, neboť zde neprobíhá komprese a URl má jen omezenou délku.

Znak	Kódování
␣	%20
!	%21
"	%22
#	%23
$	%24
%	%25
&	%26
'	%27
(	%28
)	%29
*	%2A
+	%2B
,	%2C
/	%2F
:	%3A
:	%3B
:	%3D
?	%3F
@	%40
[	%5B
]	%5D

Hlavičky umožňují klientovi a serveru předávat další informace s HTTP požadavkem nebo odpovědí. Hlavička HTTP se skládá z názvu, v němž se nerozlišují malá a velká písmena, za ním následuje dvojtečka a poté samotná hodnota.

Více viz Web API - HTTP hlavičky.

Tělo požadavku slouží k odeslaní dat klientem serveru. Tělo odpovědi naopak obsahuje data, která server odesílá klientovi. Nejčastějším textovým formátem pro výměnu dat jsou JSON a XML. Binární forma se používá pro připojení obrázků, videí, zvuku a dalších netextových souborů. Formát a velikost posílaných dat jsou popsány pomocí hlaviček Content-Type and Content-Length.

Pokud v naší implementaci posíláme binární data, např obrázky jako součást JSON, kódujeme je pomocí base64.

Stavové kódy jsou rozděleny do pěti kategorií. První číslice stavového kódu definuje třídu odpovědi, zatímco poslední dvě číslice nemají žádnou klasifikační nebo kategorizační roli. Standardem je definováno pět tříd:

• 1xx informační odpověď – požadavek byl přijat, proces pokračuje

• 2xx úspěšný – požadavek byl úspěšně přijat, pochopen a přijat

• 3xx přesměrování – pro dokončení požadavku je třeba provést další kroky

• 4xx chyba klienta – požadavek obsahuje špatnou syntaxi nebo jej nelze splnit

• 5xx chyba serveru – serveru se nepodařilo splnit zjevně platný požadavek

Důležité stavové kódy a kdy je použít:

• 200 OK - Požadavek byl úspěšný a server vrátil požadovaná data

• 201 Created - Požadavek byl úspěšný a byl vytvořen nový zdroj

• 204 No Content - Server úspěšně zpracoval požadavek a nevrací žádný obsah

• 304 Not Modified - Zdroj nebyl změněn od verze určené v hlavičce požadavku If-Modified-Since nebo If-None-Match. V takovém případě není potřeba zdroj znovu přenášet, protože klient stále má dříve staženou kopii.

• 400 Bad Request - Požadavek byl neplatný nebo nesprávný

• 401 Unauthorized - Klient postrádá platná ověřovací pověření pro požadovaný prostředek

• 403 Forbidden - Nastane pokud nemá uživatel práva na provedení požadavku

• 404 Not Found - Požadovaný zdroj nebyl na serveru API nalezen, nepoužívat pokud výsledek nějakého omezení je prázdná množina, k tomu to neslouží

• 500 Internal Server Error - Při zpracování požadavku došlo na serveru k chybě, jedná se o neočekávanou neošetřenou výjimku