1. diel - REST API a React - SOAP, GraphQL, REST a JSON

Vitajte v e-learning kurze React, kde sa zoznámime s tvorením moderných webových aplikácií pomocou REST API. Práve API klienti sú najčastejšie typy projektov v React.

Predstavenie projektu

Dnes začneme pracovať na pokročilom React projekte. Postupne si tu vytvoríme plne funkčnú klientsku aplikáciu pre databázu filmov a osobností, predstavujúcich režisérov alebo hercov. Komunikácia s databázou bude realizovaná prostredníctvom vopred pripraveného RESTful API v Node.js. Klient bude umožňovať pohodlnú správu jednotlivých záznamov (filmov aj osobností) v databáze. Ich výpis v zozname bude možné filtrovať podľa rôznych dostupných parametrov.

Tu je malá ukážka toho, ako bude vyzerať záverečná aplikácia:

REST API klient v React - Filmová databáza

Pôjde teda o podobný projekt, ako bol prehliadač pokémonov zo Základov React. API budeme mať opäť pripravené, avšak tentoraz už bude mať klient kompletnú funkcionalitu a bude napríklad dáta do databázy aj odosielať alebo ich filtrovať. Kód aplikácie bude maximálne stavať na využití funkcionality čistého JavaScriptu a samotnej knižnice React, aby bol kurz maximálne univerzálny. Ak budete chcieť neskôr pridať akékoľvek ďalšie knižnice, nie je to problém.

Minimálne požiadavky

Kurz predpokladá znalosti:

Pokiaľ niektoré zo znalostí nemáte, absolvujte prvý daný kurz.

Výhodou je skúsenosť s:

Pokiaľ nemáte znalosti Node.js, budete môcť kurz rovnako prejsť. Len nebudete rozumieť tomu, ako server funguje, čo v zásade nevadí - zameriavame sa tu na klienta v React.

Než sa vrhneme so sprevádzkovaním API servera, predstavíme si dnes rôzne druhy API, konkrétne REST API, SOAP, GraphQL a formát JSON. Tým sa pripravíme na projekt databázy filmov, ktorý budeme v tomto kurze vyvíjať.

Druhy webových API

Na webe existuje niekoľko rozšírených spôsobov komunikácie. Sú to:

jednoduchá API,
API pomocou protokolu SOAP,
API pomocou architektúry REST,
GraphQL od Facebooku.

Jednoduchá API

CSV API sme si už predstavili v lekcii Úvod do AJAX a webových API kurzu Základy React na ukážke s kurzami Č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 sú na jednotlivých riadkoch a hodnoty sú oddelené nejakým špeciálnym znakom (v CSV s menami kurzu to sú zvislítka - |, na klávesnici sa píšu pomocou AltGr + W). Častejšie sa ale používajú bodkočiarky ;. Na jednoduché API je možné použiť aj formát XML alebo JSON.

Jednoduchá API typicky ponúka len nejaký zoznam dát na stiahnutie, napr. počasie podľa mesta. Neumožňujú zložitejšiu manipuláciu s dátami.

SOAP

Skratka SOAP znamená Simple Object Access Protocol. Správy posielané pomocou protokolu SOAP sú obvykle založené na XML (čo je značkovací jazyk podobný HTML). Oproti RESTU (viď ďalej) je SOAP skôr procedurálna (REST je orientovaný na dáta). To sa prejavuje aj v spôsobe volania API. URL pri používaní SOAP bude typicky obsahovať nejaké sloveso, na rozdiel od REST, kde bude typicky nejaké podstatné meno (v našom prípade to bude podstatné meno movies, ale o tom neskôr). Jedným z najznámejších použití protokolu SOAP u nás je odosielanie tržieb pri Elektronickej evidencii tržieb (EET).

SOAP požiadavka na zaevidovanie EET tržby bez dlhej hlavičky, ktorú vypustíme, vyzerá 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žiaľ nie sú príliš jednoduché a to aj napriek tomu, že majú v názve slovo Simple. Používajú sa skôr v štátnej sfére a finančníctve na robustné projekty a nie sú častou voľbou pre klasické aplikácie.

GraphQL

Pre predstavu, že existujú aj iné aplikačné rozhrania na komunikáciu na webe, si ukážeme ešte GraphQL. To vytvoril a spopularizoval Facebook. GraphQL používa na reprezentáciu informácií koncept sociálnych grafov s vrcholmi a hranami (ako v teórii grafov). Vrcholy sú objekty ako používateľ, fotka, stránka alebo komentár. Hrany sú potom spojenie medzi objektmi ako napríklad komentáre pod fotkou.

Ukážkový dotaz nižšie získa užívateľa s id: "10", jeho meno, email a priateľov, pre ktorých získa ich mená:

{
  user(id: "10") {
    name
    email
    friends {
      name
    }
  }
}

GraphQL využijeme v prípade, keď je otázky zložité formalizovať a treba si pri každej otázke povedať, čo presne nás zaujíma.

REST

REST je v súčasnej dobe veľmi obľúbená architektúra rozhrania. Je to skratka z REpresentational State Transfer – pojmu, ktorý zaviedol vo svojej dizertačnej práci Roy Fielding. To je jeden zo spoluautorov protokolu HTTP, preto neprekvapí, že REST tento protokol používa. REST implementuje štyri základné CRUD operácie. Tieto operácie sú vytvoriť (C reate), čítať (R ead), zmeniť (U pdate) a zmazať (D elete). V HTTP protokole im zodpovedajú metódy:

GET (prečítať),
POST (vytvoriť),
PUT (upraviť),
DELETE (zmazať).

Práve používanie rôznych HTTP metód je základným princípom REST API. Napríklad by sme nemali odstraňovať dáta cez klasickú GET požiadavku, ktorú používame, keď sa snažíme otvoriť nejakú stránku.

Vďaka štyrom spomínaným metódam je REST rozhranie jednoduché na pochopenie a na používanie. Oproti SOAP je oveľa stručnejšie a teda efektívnejšie. Aj napriek svojej stručnosti obsahuje každú požiadavku všetky informácie potrebné na jeho vybavenie a server teda nemusí držať žiadny stav (je stateless). Z toho okrem iného vyplýva, že pokiaľ aplikácia potrebuje nejaký stav, musí ho držať klient.

API, ktoré používa rozhranie REST, sa označuje ako RESTful.

API nášho servera

Pre našu budúcu databázovú aplikáciu použijeme server práve s RESTful API. Budeme teda komunikovať pomocou spomínaných štyroch HTTP metód a odosielať/prijímať budeme dáta vo formáte JSON. Tu je krátka ukážka formátu JSON reprezentujúca 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"
        }
    ]
}

Dokumentácia k API

Náš klient v React musí vedieť pracovať presne s tým API, ktoré poskytuje daný server. V našom prípade je to API z kurzu Node.js, ktorého rozhranie je kompletne popísané v lekcii Dokumentácia k Node.js API. Na túto dokumentáciu sa teraz môžete pozrieť. Naša práca sa bude neustále točiť okolo tohto dokumentu, aby naše endpointy mali správne adresy a prijímali a odosielali JSON v správnom formáte.

Endpointy sú vyústenia nášho API, s ktorými sa dá zvonku komunikovať.

Pri odosielaní požiadavky pomocou RESTful API nám k tomu, aby bola požiadavka spracovaná tak ako potrebujeme, napomáha správne použitie URL adresy. Napr. pre prácu s dátami o filmoch budeme podľa danej dokumentácie neskôr používať tieto adresy:

POST

Pre vytvorenie nového filmu nám klient pošle POST požiadavku (vytvorenie, zodpovedá CREATE metóde CRUD) na adresu:

/api/movies

(nie je potrebné zadávať id filmu, ide o vytvorenie položky v databáze, databáza si vytvorí id sama)

GET

Pre zoznam všetkých filmov bude klient posielať na náš server GET požiadavky (čítanie, zodpovedá READ metóde CRUD) na adresu:

/api/movies

A pre jeden konkrétny film:

/api/movies/(id)

Výraz (id) vždy nahradíme identifikátorom daného filmu.

Pút

Pre PUT požiadavku upravujúcu daný film (editácia, zodpovedá UPDATE metóde CRUD) bude adresa nasledujúca:

/api/movies/(id)

Delite

A pre DELETE požiadavku (zmazanie, zodpovedá DELETE metóde CRUD) pristúpi klient na adresu:

/api/movies/(id)

Článok pre vás napísal Petr Sedláček

Užívateľské hodnotenie:

Ešte nikto nehodnotil, buď prvý!

Aktivity