Lekce 1 - REST API a React - SOAP, GraphQL, REST a JSON
Vítejte v e-learning kurzu React, kde se seznámíme s tvořením moderních webových aplikací pomocí REST API. Právě API klienti jsou nejčastějšími typy projektů v React.
Představení projektu
Dnes začneme pracovat na pokročilém React projektu. Postupně si zde vytvoříme plně funkční klientskou aplikaci pro databázi filmů a osobností, představujících režiséry nebo herce. Komunikace s databází bude realizována prostřednictvím předem připraveného RESTful API v Node.js. React klient bude umožňovat pohodlnou správu jednotlivých záznamů (filmů i osobností) v databázi. Jejich výpis v seznamu bude možné filtrovat podle různých dostupných parametrů.
Zde je malá ukázka toho, jak bude vypadat závěrečná aplikace:
Půjde tedy o podobný projekt, jako byl prohlížeč pokémonů ze Základů React. API budeme mít opět připravené. Ovšem tentokrát již bude mít klient kompletní funkcionalitu a bude například data do databáze i odesílat nebo je filtrovat. Kód aplikace bude maximálně stavět na využití funkcionality čistého JavaScriptu a samotné knihovny React, aby byl kurz maximálně univerzální. Pokud budete chtít později přidat jakékoli další knihovny, není to problém.
Minimální požadavky
Kurz předpokládá znalosti:
Pokud některé ze znalostí nemáte, absolvujte nejdříve daný kurz.
Výhodou je zkušenost s:
Pokud nemáte znalosti Node.js, budete moci kurz stejně projít. Jen nebudete rozumět tomu, jak server funguje, což v zásadě nevadí - zaměřujeme se zde na klienta v Reactu.
Než se vrhneme se zprovoznění API serveru, představíme si dnes různé druhy API, konkrétně REST API, SOAP a GraphQL. Tím se připravíme na projekt databáze filmů.
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
Jednoduché CSV API s kurzy ČNB jsme si již představili v lekci Úvod do AJAX a webových API kurzu Základy React. Nalezneme jej na této adrese a vrací nám takováto data:
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, častěji se
však 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 REST API (viz dále) jsou SOAP API 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á a to i 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, email 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 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 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šeho serveru
Pro naši budoucí databázovou aplikaci použijeme server právě s RESTful API. Budeme tedy komunikovat pomocí zmíněných čtyř HTTP metod. Odesílat/přijímat budeme data ve formátu JSON. 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" } ] }
Dokumentace k API
Náš klient v React musí umět pracovat přesně s tím API, které poskytuje daný server. 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, abychom posílali naše AJAX dotazy na správné endpointy a přijímali a odesílali JSON ve správném formátu.
Endpointy jsou vyústění 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:
POST
Pro vytvoření nového filmu klient pošle POST požadavek (vytvoření, odpovídá CREATE metodě z CRUD) na adresu:
/api/movies
(Není potřeba zadávat id filmu, jde o vytvoření položky v databázi, databáze si vytvoří id sama.)
GET
Pro seznam všech filmů bude klient posílat na náš server GET požadavky (čtení, odpovídá READ metodě z 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.
PUT
Pro PUT požadavek upravující daný film (editace, odpovídá UPDATE metodě z CRUD) bude adresa následující:
/api/movies/(id)
DELETE
A pro DELETE požadavek (smazání, odpovídá DELETE metodě z CRUD) přistoupí klient na adresu:
/api/movies/(id)
Příště, v lekci Databázový klient v React - MongoDB a React projekt, si nainstalujeme databázi MongoDB a vytvoříme nový React projekt pro klientskou aplikaci.
