RESTful API TAMZ 1 Cvičení 11
REST Architektura rozhraní navržená pro distribuované prostředí Pojem REST byl představen v roce 2000 v disertační práci Roye Fieldinga, zkratka z Representional State Transfer Rozhraní REST je použitelné pro jednotný a snadný přístup ke zdrojům (resources) Zdrojem mohou být data, stejně jako stavy aplikace Všechny zdroje mají vlastní identifikátor URI Čtyři základní metody pro přístup k datům Používají přístup, reprezentovaný zkratkou CRUD Create (C) Vytvoření dat Retrieve (R) Získání požadovaných dat Update (U) Změna, aktualizaci dat Delete (D) Smazání dat Metody jsou implementovány pomocí odpovídajících metod HTTP protokolu
Adresovatelnost REST je zaměřen především na zdroje (resources) Každý zdroj by měl být dosažitelný pomocí jedinečného identifikátoru URI Příklad: scheme://host:port/path?querystring#fragment scheme protokol (např. HTTP) host DNS nebo IP adresa port číslo TCP portu path virtuální hierarchická struktura querystring množina párů klíč=hodnota, oddělených znakem & fragment identifikátor, který označuje nějakou část zdroje (např. nadpis nebo obrázek)
Metody přístupu ke zdrojům (C, R) GET (Retrieve) Určen pro read-only operace Základní metoda pro přístup ke zdrojům Například pro načtení seznamu zdrojů nebo obsahu jednoho zdroje Lze volat opakovaně se stále stejným výsledkem POST (Create) Slouží pro vytvoření dat Není ve chvíli volání metody znám přesný identifikátor (zdroj ještě neexistuje) Používá se domluvený společný identifikátor ( endpoint ) S každým voláním se mění stav daného zdroje/služby Po odeslání by měl server vrátit návratový kód 201 - Created
Metody přístupu ke zdrojům (U, D) DELETE (Retrieve) Smaže zdroj pomoci volání URI, HTTP metoda DELETE Volání je obdobné volání metody GET V praxi bývá někdy problematické Někdy se nahrazuje metodou POST s parametrem PUT(Update) Operace pro změnu zdroje Podobná operaci vytvoření (create, metoda POST) Voláme konkrétní URI konkrétního zdroje, který chceme změnit Nová hodnota se předává v těle Obdobně jako u delete bývá v praxi problematická
Stavové kódy 200 OK požadavek proběhl v pořádku 201 Created při POST, pokud byl vytvořen nový obsah 204 No Content požadavek na server proběhne v pořádku, ale server nic nevrátí 304 Not Modified pokud nebyl od posledního požadavku 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 Not Found zdroj není nalezen 405 Method Not Allowed zdroj není dostupný pro tuto metodu. 410 Gone zdroj není už na téhle adrese dostupný 415 Unsupported Media Type klient v požadavku na server uvedl hlavičku Content-Type, kterou server nepodporuje 429 Too-Many Requests pokud klient překročil maximální počet požadavků, třeba za den
Reprezentace dat Klient nepracuje přímo se zdroji ale s jeho reprezentací Resource může mít různé reprezentace Záleží na službě, které formáty podporuje Nejpoužívanější je JSON, XML, RSS, YAML, apod. Formát definujeme obvykle v URI nebo v http hlavičce Content-Type. Příklad v URI: http://server/data.xml Příklad v http hlavičce: Content-Type: application/xml
Backbone.js Malý populární generický MVC framework Pro psaní náročnějších HTML5 webových a mobilních aplikací objektový model s dědičností REST (REpresentational State Transfer) Sync Operace nad kolekcemi (POST = Create, GET = Read) Operace nad modelem (PUT = Update, DELETE = Delete) Lze využít s jquery/... k manipulaci s DOM MVC v Backbone.js Model reprezentuje jednu datovou entitu, většinou provázanou s View, které je aktualizováno při každé změně. Backbone.View je ve skutečnosti Controller Views lze renderovat pomocí jquery nebo použít template
Úkol (1b) využití REST API Využijte ve své aplikaci API služby, předvedené cvičícím Vložení dat (C: metoda POST, zaslán query string): http://homel.vsb.cz/~mor03/rest/api.php?request=message Získání dat (R: metoda GET, vráceno pole objektů): http://homel.vsb.cz/~mor03/rest/api.php?request=message http://homel.vsb.cz/~mor03/rest/api.php?request=message/2 http://homel/~mor03/rest/api.php?request=message/nick/aaa http://homel.vsb.cz/~mor03/rest/api.php?request=message/last Aktualizace dat (U: metoda PUT, zaslán json/query str.): http://homel.vsb.cz/~mor03/rest/api.php?request=message/2 Alternativa, pokud nelze použít PUT, ale použijeme POST: http://homel.vsb.cz/~mor03/rest/api.php?request=edit/2 Odstranění dat (D: metoda DELETE, pouze ID): http://homel.vsb.cz/~mor03/rest/api.php?request=message/2 Alternativa, pokud nelze použít PUT, ale použijeme POST: http://homel.vsb.cz/~mor03/rest/api.php?request=delete/2 Formát datového objektu (aktualizovatelné informace): {"id":2,"nick":'anon',"text":"hello", token: "secret_for_du", "timestamp":"2014-04-23 20:24:17"}