2. diel - REST API, SOAP, GRAPH a JSON

V minulej lekcii, Úvod do Node.js , sme si nainštalovali a predstavili Node. Dnes bude reč o rôznych druhoch API a formátu JSON, čím sa pripravíme na projekt, ktorý budeme v tomto kurze vyvíjať.

Predstavenie projektu

V tomto kurze budeme vytvárať jednoduché backendové API pre správu databázy filmov. Budeme môcť dáta o filmoch pridávať, upravovať alebo mazať a samozrejme si ich aj prezerať. Práve API sú najčastejšie typy projektov v Node.js. K databáze filmov budeme pristupovať pomocou Restful API a budeme používať formát JSON ... počkať, počkať, čo znamenajú všetky tie skratky?

Api

API je skratka pre Application Programming Interface, česky aplikačné programové rozhranie. Je to všeobecne čokoľvek, čo umožňuje jednotlivým častiam softvéru komunikovať medzi sebou. Jedná sa o súhrn funkcií a procedúr, tried, komunikačných protokolov a ďalších nástrojov. Ide o to, aby metódy pre komunikáciu boli presne definované. Programátor, ktorý vytvára nový komponent systému, potom vie (alebo môže nájsť v dokumentácii), aké postupy môže použiť, aby jeho časť správne fungovala v rámci ostatných komponentov.

Ak si chcete API predstaviť ako niečo z bežného života, tak si predstavte čašníka v reštaurácii, ktorý zaisťuje (a prekladá) komunikáciu medzi hosťom a kuchárom. Alebo ako palubnú dosku automobilu, ktorá pomocou presne definovaných metód (tlačidlá na doske) odovzdá to, čo vodič (jeden komponent) chce iné komponente (motora). A návod k autu je ako API dokumentácia, kde sú jednotlivé metódy (tlačidla) opísané.

Existujú grafická API, API pre frameworky a knižnice, API operačných systémov, ale nás budú zaujímať hlavne webová API.

Webová API

Webové API definuje, ako spolu komunikujú nejaké komponenty po internete. Typicky sa jedná o 2 časti aplikácie (webová stránka si doťahuje zo servera potrebné dáta pomocou AJAX dotazu) alebo 2 rôzne aplikácie (mobilné aplikácie si sťahuje dáta z webu). Synonymom môže byť webová služba. Naše webové API bude umožňovať vykonávať operácie nad databázou filmov, napr. Vyhľadá existujúci film alebo vloží film nový. Webová API samozrejme nie sú obmedzená len na databázy, môžeme cez ne posielať SMS, zistiť aktuálne počasie a podobne.

Ukážka webového API

Malinké, ale veľmi populárne API medzi českými e-shopy, beží na stránkach Českej národnej banky, konkrétne na adrese: https://www.cnb.cz/...nni_kurz.txt

Keď si adresu otvoríte, vypíše sa vám kurz mien pre aktuálny deň. Všimnite si, že sa nevygeneroval žiadna HTML stránka, ale surové dáta vo formáte CSV. Webová API totiž nie sú určené pre ľudí, ale pre programy. Výstup API vyzerá takto:

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

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
Graph API od Facebooku

Jednoduchá API

CSV API sme si už predstavili na ukážke s kurzami ČNB. Položky sú na jednotlivých riadkoch a hodnoty sú oddelené nejakým špeciálnym znakom (v CSV s menami kurze to sú zvislou čiarou). Na jednoduchá API sa môže používať aj formát XML alebo JSON.

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

Soap

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

SOAP požiadavku na zaevidovaní EET tržby by bez dlhé hlavičky, ktorú som vypustil, vyzeral napr. 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íctva na robustné projekty a nie sú častou voľbou pre klasické aplikácie.

Resta

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 élet). V HTTP protokolu im odpovedajú 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 spomenutým metódam je REST rozhranie jednoduché na pochopenie a na používanie. Oproti Soap je oveľa stručnejší 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 ak aplikácia potrebuje nejaký stav, musí ho držať klient.

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

Graph API

Pre predstavu, že existujú aj iné aplikačné rozhranie pre komunikáciu na webe, si ukážeme ešte Graph API. To vytvoril a spopularizoval Facebook, ktorý cez neho servíruje veľmi rozmanitá dáta. Facebooku sa totiž môžeme opýtať na toľko vecí, že by REST alebo dokonca SOAP požiadavky boli veľmi neprehľadné. Graph API používa pre reprezentáciu informácií koncept sociálnych grafov s vrcholmi a hranami (ako v teórii grafov). Vrcholy sú objekty ako užívateľ, fotka, stránka alebo komentár. Hrany sú potom spojenie medzi objektmi ako napríklad komentáre pod fotkou. A dáta sú uložené v poliach objektov.

Ukážkový dotaz nižšie sa Facebooku pýta na narodeniny, email a mesto daného užívateľa:

https://graph.facebook.com/{your-user-id}
    ?fields=birthday,email,hometown
    &access_token={your-user-access-token}

Graph API využijeme v prípade, keď je dotazy zložité formalizovať a je potrebné si pri každom dotaze povedať, čo presne nás zaujíma.

Api našej aplikácie

Pre našu aplikáciu použijeme práve Restful API, a to z vyššie uvedených dôvodov (jednoduchosť, stručnosť) a tiež preto, že potrebujeme nad filmy vykonávať operácie, pre ktoré je navrhnuté. Ďalším dôvodom je, že aj keď REST podporuje mnoho formátov, prevláda používanie formátu JSON.

O formáte JSON si ešte dnes niečo povieme, zatiaľ spomeniem len to, že je vhodný pre webové prehliadače a pre nás bude praktický iz dôvodu použitej databázy - o tej si povieme v niektorom z budúcich článkov.

Pri odosielaní požiadavke pomocou Restful API nám k tomu, aby bola požiadavka spracovaný tak, ako potrebujeme, napomáha správne použitie cesty. Pre našu prvú tabuľku, ktorá bude obsahovať dáta o filmoch, budeme v našej aplikácii používať tieto cesty (výraz id vždy nahradíme príslušným identifikátorom):

Pošta

Pre POST požiadavka (vytvorenie, zodpovedá CREATE metóde CRUD) bude adresa:

/api/movies

(Nie je potrebné zadávať id filmu, ide o vytvorenie položky v databáze, databázy si vytvoria id sama)

Get

Pre GET požiadavku (čítanie, zodpovedá READ metóde CRUD) použijeme pre všetky filmy adresu:

/api/movies

A pre jeden konkrétny film:

/api/movies/(id)

Put

Pre PUT požiadavku (editácia, zodpovedá UPDATE metóde CRUD) bude adresa nasledujúce:

/api/movies/(id)

Dele

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

/api/movies/(id)

JSON

Už som spomínal, že Restful API používa prevažne formát JSON. A čo to teda je?

JSON (skratka za JavaScript Object Notation) je formát používaný na uchovávanie dát i ku komunikácii na webe. Hoci vychádza z JavaScriptu, používajú ho aj iné jazyky. Jeho syntax je veľmi podobná syntax objektov a polí v JavaScripte, s niekoľkými obmedzeniami. Mená vlastností musí byť vždy v dvojitých úvodzovkách a sú povolené iba jednoduchá dáta - žiadne výpočty ani volanie funkcií. Komentáre nie sú povolené.

Tu máte krátku ukážku formáte JSON reprezentujúci hudobníka, jeho hudobnú skupinu a jej albumu:

[
    {
        "name": "Trent",
        "last name": "Reznor",
        "band name": "Nine Inch Nails",
        "born": 1965,
        "male": true,
        "albums": [
            "Pretty Hate Machine",
            "The Downward Spiral",
            "The Fragile",
            "With Teeth",
            "Year Zero",
            "to be continued..."
        ]
    }
]

V budúcej lekcii, Rozbehnutie projektu a prvé riadky v Expressu , sa zoznámime s knižnicou Express. Prejdeme si založenie nového projektu a implementujeme si prvú z metód Restful API, metódu GET.

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

Užívateľské hodnotenie:

5 hlasov

Aktivity

Najčastejšie vyhľadávané

2. diel - REST API, SOAP, GRAPH a JSON

Predstavenie projektu

Api

Webová API

Ukážka webového API

Druhy webových API

Jednoduchá API

Soap

Resta

Graph API

Api našej aplikácie

Pošta

Get

Put

Dele

JSON