Lekce 2 - REST API v Django REST - SOAP, GraphQL, REST a JSON Nové
V minulé lekci, REST API v Django REST - Úvod do webových API, jsme si vysvětlili, proč se moderní aplikace vytvářejí pomocí API serveru a jak takový server funguje.
V dnešním Django REST Framework tutoriálu si představíme různé druhy API, konkrétně REST API, SOAP, GraphQL a formát JSON. Tím se připravíme na projekt databáze filmů, který budeme v tomto Python kurzu vyvíjet.
Druhy webových API
Na webu existuje několik rozšířených způsobů komunikace. Jsou to:
- jednoduchá API,
- API pomocí protokolu SOAP,
- API pomocí architektury REST,
- GraphQL od Facebooku.
Jednoduchá API
CSV API jsme si již představili na ukázce s kurzy ČNB:
07.01.2019 #4 země|měna|množství|kód|kurz Austrálie|dolar|1|AUD|15,947 Brazílie|real|1|BRL|6,053 Bulharsko|lev|1|BGN|13,076 Čína|žen-min-pi|1|CNY|3,262 Dánsko|koruna|1|DKK|3,425 EMU|euro|1|EUR|25,575 Filipíny|peso|100|PHP|42,647 Hongkong|dolar|1|HKD|2,852 Chorvatsko|kuna|1|HRK|3,442 Indie|rupie|100|INR|32,093 Indonesie|rupie|1000|IDR|1,586 Island|koruna|100|ISK|18,916 Izrael|nový šekel|1|ILS|6,049 Japonsko|jen|100|JPY|20,641 Jižní Afrika|rand|1|ZAR|1,612 Kanada|dolar|1|CAD|16,737 Korejská republika|won|100|KRW|1,996 Maďarsko|forint|100|HUF|7,965 Malajsie|ringgit|1|MYR|5,431 Mexiko|peso|1|MXN|1,156 MMF|ZPČ|1|XDR|31,079 Norsko|koruna|1|NOK|2,609 Nový Zéland|dolar|1|NZD|15,111 Polsko|zlotý|1|PLN|5,960 Rumunsko|leu|1|RON|5,485 Rusko|rubl|100|RUB|33,405 Singapur|dolar|1|SGD|16,467 Švédsko|koruna|1|SEK|2,502 Švýcarsko|frank|1|CHF|22,780 Thajsko|baht|100|THB|69,878 Turecko|lira|1|TRY|4,169 USA|dolar|1|USD|22,347 Velká Británie|libra|1|GBP|28,501
Položky jsou na jednotlivých řádcích a hodnoty jsou oddělené nějakým
speciálním znakem (v CSV s měnami kurzu to jsou svislítka - |
,
na klávesnici se píšou pomocí AltGr + W). Častěji se
ale používají středníky ;
. Na jednoduchá API je možné
použít i formát XML nebo JSON.
Jednoduchá API typicky nabízí jen nějaký seznam dat ke stažení, např. počasí podle města. Neumožňují složitější manipulaci s daty.
SOAP
Zkratka SOAP znamená Simple
Object Access Protocol.
Zprávy posílané pomocí protokolu SOAP jsou obvykle založené na
XML (což je značkovací jazyk podobný HTML). Oproti RESTu
(viz dále) je SOAP spíše procedurální (REST je
orientovaný na data). To se projevuje i ve způsobu volání API. URL při
používání SOAP bude typicky obsahovat nějaké sloveso, na rozdíl
od REST, kde bude typicky nějaké podstatné jméno (v našem
případě to bude podstatné jméno movies
, ale o tom později).
Jedním z nejznámějších použití protokolu SOAP u nás je odesílání
tržeb při Elektronické evidenci tržeb (EET).
SOAP požadavek na zaevidování EET tržby bez dlouhé hlavičky, kterou vypustíme, vypadá takto:
<soap:Body wsu:Id="id-16FE2A6FC1AFE42BE9146412186273614"> <Trzba> <Hlavicka dat_odesl="2016-09-19T19:06:37+01:00" prvni_zaslani="false" uuid_zpravy="9edeb22b-4234-4047-869c-3a76f86c20d3"/><Data celk_trzba="34113.00" cerp_zuct="679.00" cest_sluz="5460.00" dan1="-172.39" dan2="-530.73" dan3="975.65" dat_trzby="2016-01-05T00:30:12+01:00" dic_popl="CZ00000019" id_pokl="/5546/RO24" id_provoz="273" porad_cis="0/6460/ZQ42" pouzit_zboz1="784.00" pouzit_zboz2="967.00" pouzit_zboz3="189.00" rezim="0" urceno_cerp_zuct="324.00" zakl_dan1="-820.92" zakl_dan2="-3538.20" zakl_dan3="9756.46" zakl_nepodl_dph="3036.00"/> <KontrolniKody> <pkp cipher="RSA2048" digest="SHA256" encoding="base64">W7UlA4hXNsDLvCj/eeRAYeOAsNsgMSdltcJNIW98KQRsfspTMW0Lr/OGQgRHZfO5KjolZgzN3k9mgzrVoX2+N90fCNEnOri2kjrW5vzTgMK6OZ9IryAEg0xFZjjjCQ0qKsQsVi8OLQOn3ZnN/BUGG2SIduER+iIOrhfOmes7OXaa5/2jQSfPTHZHZ/Bxhqld3gL4PHvd7sevZYUupHpE1fM7Uw1+lu8i1YOdghZoMyOfKw7FcqvRJpHrW/JZL5Dr5iCgu5ClmhZrb3hZavsxlDG7P2cUhSQgmEVTxJ2n38q/Cf91KE8e52SODN4Q8BfncXpmtkQ7Go3KsRsY3xN7xg== </pkp> <bkp digest="SHA1" encoding="base16">1F1A2D90-4EAD34A8-411CFB0B-EB17616E-B2CE8114</bkp> </KontrolniKody> </Trzba> </soap:Body>
SOAP API bohužel nejsou příliš jednoduchá, přestože mají v názvu slovo Simple. Používají se spíše ve státní sféře a finančnictví na robustní projekty a nejsou častou volbou pro klasické aplikace.
GraphQL
Pro představu, že existují i jiná aplikační rozhraní pro komunikaci na webu, si ukážeme ještě GraphQL. To vytvořil a zpopularizoval Facebook. GraphQL používá pro reprezentaci informací koncept sociálních grafů s vrcholy a hranami (jako v teorii grafů). Vrcholy jsou objekty jako uživatel, fotka, stránka nebo komentář. Hrany jsou pak spojení mezi objekty jako třeba komentáře pod fotkou.
Ukázkový dotaz níže získá uživatele s id: "10"
, jeho
jméno, e-mail a přátele, pro které získá jejich jména:
{ user(id: "10") { name email friends { name } } }
GraphQL využijeme v případě, kdy je dotazy složité formalizovat a kdy je třeba si při každém dotazu říci, co přesně nás zajímá.
REST
REST je v současné době velmi oblíbená architektura rozhraní. Je to zkratka odvozená z REpresentational State Transfer - pojmu, který zavedl ve své disertační práci Roy Fielding. To je jeden ze spoluautorů protokolu HTTP, proto nepřekvapí, že REST tento protokol používá. REST implementuje čtyři základní CRUD operace. Tyto operace jsou vytvořit (Create), číst (Read), změnit (Update) a smazat (Delete). V HTTP protokolu jim odpovídají metody:
GET
(přečíst),POST
(vytvořit),PUT
(upravit),DELETE
(smazat).
Právě používání různých HTTP metod je
základním principem REST API. Například bychom neměli
odstraňovat data přes klasický GET
požadavek, který
používáme, když se snažíme otevřít nějakou stránku.
Díky čtyřem zmíněným metodám je REST rozhraní jednoduché na pochopení a na používání. Oproti SOAP je mnohem stručnější a tedy efektivnější. I přes svoji stručnost obsahuje každý požadavek všechny informace potřebné k jeho vyřízení a server tedy nemusí držet žádný stav (je stateless). Z toho mimo jiné vyplývá, že pokud aplikace potřebuje nějaký stav, musí ho držet klient.
API, které používá rozhraní REST, se označuje jako RESTful.
API naší aplikace
Pro naši budoucí databázovou aplikaci použijeme právě RESTful API. Učiníme tak z výše uvedených důvodů (jednoduchost, stručnost) a také proto, že potřebujeme nad filmy provádět operace, pro které je REST navržené. Dalším důvodem je, že i když REST podporuje mnoho formátů, převládá používání formátu JSON.
Formát JSON
JSON (zkratka za
JavaScript Object
Notation) je formát používaný k uchovávání dat i ke
komunikaci na webu. Přestože vychází z JavaScriptu,
používají ho i jiné jazyky. Jeho syntaxe je velmi podobná syntaxi objektů
(složené závorky {}
) a polí (hranaté závorky []
)
v JavaScriptu, jen s několika omezeními. Jména vlastností musí být vždy
ve dvojitých uvozovkách a jsou povolena pouze jednoduchá data - žádné
výpočty ani volání funkcí. Komentáře nejsou povoleny.
Zde je krátká ukázka formátu JSON reprezentující film Star Wars VI:
{ "_id": "640471c9b80ed070c5425fbc", "name": "Star Wars VI", "year": 1983, "directorID": "64047109b80ed070c5425fb8", "actorIDs": [ "64047e10b3201657ed2b5977" ], "genres": [ "sci-fi" ], "isAvailable": true, "dateAdded": "2023-03-05T10:41:13.608Z", "__v": 0, "director": { "_id": "64047109b80ed070c5425fb8", "name": "James Francis Cameron" }, "actors": [ { "_id": "64047e10b3201657ed2b5977", "name": "Dwayne Johnson" } ] }
Vidíme zde jeden hlavní objekt definovaný pomocí
{}
, který reprezentuje film a obsahuje spoustu
vlastností. Řetězce jsou v uvozovkách, čísla píšeme bez
nich. Několik vlastností obsahuje buď další objekt
zapsaný opět pomocí {}
(režisér director
) nebo
pole zapsané hranatými závorkami []
(ID herců
ve filmu actorIDs
).
JSON je vhodný pro webové prohlížeče, ale je lehce čitelný i člověkem.
Dokumentace k API
Náš server v Pythonu musí poskytovat přesně to API, se kterým umí pracovat daný klient. V našem případě je to API z kurzu Node.js, jehož rozhraní je kompletně popsané v lekci Dokumentace k Node.js API. Na tuto dokumentaci se nyní můžete podívat. Naše práce se bude neustále točit okolo tohoto dokumentu, aby naše endpointy měly správné adresy a přijímaly a odesílaly JSON ve správném formátu.
Endpointy jsou vyústění našeho API, se kterými se dá zvenku komunikovat.
Při odesílání požadavku pomocí RESTful API nám k tomu, aby byl požadavek zpracován, tak jak potřebujeme, napomáhá správné použití URL adresy. Např. pro práci s daty o filmech budeme podle dané dokumentace později používat tyto adresy:
Požadavek POST
Pro vytvoření nového filmu nám klient pošle POST
požadavek
(vytvoření, odpovídá CREATE metodě CRUD) na adresu:
/api/movies
V tomto požadavku není potřeba zadávat id filmu, jde o vytvoření položky v databázi, databáze si vytvoří id sama.
Požadavek GET
Pro seznam všech filmů bude klient posílat na náš server
GET
požadavky (čtení, odpovídá READ metodě
CRUD) na adresu:
/api/movies
A pro jeden konkrétní film:
/api/movies/(id)
Výraz (id)
vždy nahradíme identifikátorem daného filmu.
Požadavek PUT
Pro PUT
požadavek upravující daný film (editace, odpovídá
UPDATE metodě CRUD) bude adresa následující:
/api/movies/(id)
Požadavek DELETE
A pro DELETE
požadavek (smazání, odpovídá
DELETE metodě CRUD) přistoupí klient na adresu:
/api/movies/(id)
To je pro dnešní lekci vše.
V příští lekci, REST API v Django REST - Angular/React projekt, si zprovozníme javascriptového klienta, kterého budeme později využívat ke komunikaci s naším Django REST API.