Vecný obsah, základné pojmy - Web API

REST je architektúrou rozhrania, ktorá je navrhnutá pre distribuované prostredie. Na rozdiel od známych XML-RPC alebo SOAP je REST orientovaný dátovo a nie procedurálne. Stav aplikácie a správanie je vyjadrené takzvaným zdrojom (resource), každý zdroj musí mať unikátny identifikátor URL. REST podporuje štyri základné metódy, ktoré sú známe pod označením CRUD, teda vytvorenie dát (Create), získanie požadovaných dát (Retrieve), zmenu (Update) a vymazanie (Delete). Tieto metódy sú implementované pomocou zodpovedajúcich metód HTTP protokolu.

Požiadavky kladené na architektonický štýl vyhovujúci paradigme REST:

• Oddelený klient-server - Pri návrhu Web API musia byť klientske a serverové aplikácie od seba úplne nezávislé. Jedinou informáciou, ktorú by klientska aplikácia mala poznať, je URI požadovaného zdroja.
• Bezstavovosť - Každá požiadavka musí obsahovať všetky informácie nevyhnutné pre jej spracovanie. Web API nevyžadujú žiadne relácie na strane servera. Serverové aplikácie nesmú ukladať žiadne dáta súvisiace s požiadavkou klienta.
• Ukladanie do vyrovnávacej pamäte - Ak je to možné, mali by byť prostriedky kešovateľné na strane klienta alebo servera. Odpovede servera tiež musia obsahovať informácie o tom, či je pre dodaný zdroj povolené ukladanie do vyrovnávacej pamäte. Cieľom je zlepšiť výkon na strane klienta a zároveň zvýšiť škálovateľnosť na strane servera.
• Jednotné rozhranie - Všetky požiadavky API na rovnaký zdroj by mali vyzerať rovnako, bez ohľadu na to, odkiaľ požiadavka pochádza.
• Viacvrstvový systém - V Web API prechádzajú volania a odpovede rôznymi vrstvami. Vo všeobecnosti platí, že sa klientske a serverové aplikácie nepripájajú priamo k sebe. V komunikačnej slučke môže byť rad rôznych sprostredkovateľov. Rozhranie Web API musí byť navrhnuté tak, aby klient ani server neboli ovplyvnení tým, či komunikujú s koncovou aplikáciou alebo sprostredkovateľom.

HTTP je komunikačný protokol, ktorý sa využíva na komunikáciu webového servera s klientským softvérom. HTTP je založený na zasielaní požiadaviek a odpovedí na ne. Klient vykoná HTTP požiadavku (request) a webový server mu na ňu odpovie pomocou HTTP odpovedí (response).

URL adresa rozhrania API je štruktúrovaná podobne ako „bežná“ adresa URL webových stránok, ale konvencie pomenovania sú trochu iné a zvyčajne dodržiavajú prísnejšiu organizačnú logiku.

URL adresa v API má zvyčajne 5 častí:

• Základná URL – je počiatočnou časťou URL adresy rozhrania API. Skladá sa z protokolu, hostiteľa a portu. Napr.: http://localhost:80
• Názov spojenia - časť URL určujúca, nad akým DB spojením má server vykonať požiadavku. Napr.: /develop
• Kontrolér - organizačný celok, typicky názov BO v množnom čísle. Napr.: /storecards

• Koncový bod (endpoint) - identifikuje, ku ktorému zdroju chce klient pristupovať. Napr.: /{id}.

  Ak vykonávate dotaz nad konkrétnym BO, potom použite endpoint, napr.: /{id}/confirm, a neodovzdávajte id ako query parameter ani v tele dotazu.

• Query string – skladá sa z query parametrov, ktoré slúžia na doplnenie API dotazu o dodatočné informácie ovplyvňujúce jeho spracovanie. Napr.: ?executor=outprocess

Úplná URL adresa rozhrania API spojí tieto segmenty do URL adresy:

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

Query string

Parametre sa zapisujú tak, že za adresou nasleduje otáznik a za ním zapísané páry vo formáte kľúč=hodnota. Páry sú oddelené znakom &. V prípade pravdivostného parametra, ak je uvedený ako posledný parameter v query stringu, netreba uvádzať hodnotu a berie sa, ako keby bola použitá hodnota True.

Query string primárne neslúži na prenos dát, ale metadát, nepoužívajte ho napríklad na odovzdanie zoznamu ID, to patrí do tela, pretože tu neprebieha kompresia a URL má len obmedzenú dĺžku.

Kódovanie URL

Rezervované znaky majú v URL zvláštny význam a ak majú byť použité mimo ich vyhradeného významu, musia byť zakódované.

Query string primárne neslúži na prenos dát, ale metadát, nepoužívajte ho napríklad na odovzdanie zoznamu ID, to patrí do tela, pretože tu neprebieha kompresia a URL má len obmedzenú dĺžku.

Znak	Kódovanie
␣	%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 odovzdávať ďalšie informácie s HTTP požiadavkou alebo odpoveďou. Hlavička HTTP sa skladá z názvu, v ktorom sa nerozlišujú malé a veľké písmená, za ním nasleduje dvojbodka a potom samotná hodnota.

Viac viď Web API - HTTP hlavičky.

Telo požiadavky slúži na odoslanie dát klientom serveru. Telo odpovede naopak obsahuje dáta, ktoré server odosiela klientovi. Najčastejším textovým formátom pre výmenu dát sú JSON a XML. Binárna forma sa používa na pripojenie obrázkov, videí, zvuku a ďalších netextových súborov. Formát a veľkosť posielaných dát sú opísané pomocou hlavičiek Content-Type and Content-Length.

Ak v našej implementácii posielame binárne dáta, napr. obrázky ako súčasť JSON, kódujeme ich pomocou base64.

Stavové kódy sú rozdelené do piatich kategórií. Prvá číslica stavového kódu definuje triedu odpovede, zatiaľ čo posledné dve číslice nemajú žiadnu klasifikačnú alebo kategorizačnú úlohu. Štandardom je definovaných päť tried:

• 1xx informačná odpoveď – požiadavka bola prijatá, proces pokračuje

• 2xx úspešný – požiadavka bola úspešne prijatá, pochopená a prijatá

• 3xx presmerovanie – na dokončenie požiadavky je potrebné vykonať ďalšie kroky

• 4xx chyba klienta – požiadavka obsahuje nesprávnu syntax alebo ju nemožno splniť

• 5xx chyba servera – serveru sa nepodarilo splniť zjavne platnú požiadavku

Dôležité stavové kódy a kedy ich použiť:

• 200 OK - Požiadavka bola úspešná a server vrátil požadované dáta

• 201 Created - Požiadavka bola úspešná a bol vytvorený nový zdroj

• 204 No Content - Server úspešne spracoval požiadavku a nevracia žiadny obsah

• 304 Not Modified - Zdroj nebol zmenený od verzie určenej v hlavičke požiadavky If-Modified-Since alebo If-None-Match. V takom prípade nie je potrebné zdroj znova prenášať, pretože klient stále má skôr stiahnutú kópiu.

• 400 Bad Request - Požiadavka bola neplatná alebo nesprávna

• 401 Unauthorized - Klientovi chýbajú platné overovacie poverenia pre požadovaný prostriedok

• 403 Forbidden - Nastane, ak používateľ nemá práva na vykonanie požiadavky

• 404 Not Found - Požadovaný zdroj nebol na serveri API nájdený, nepoužívať, ak výsledkom nejakého obmedzenia je prázdna množina, na to to neslúži

• 500 Internal Server Error - Pri spracovaní požiadavky došlo na serveri k chybe, ide o neočakávanú neošetrenú výnimku