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

Vitajte v e-learning kurze Spring Boot, kde sa zoznámime s tvorením moderných webových aplikácií pomocou REST API.

Dnes si predstavíme 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ť.

Minimálne požiadavky

Kurz predpokladá znalosti:

Javy SE (štandardná edícia), najmä:
- Základov a
- OOP
HTML a CSS
Základné princípy frameworku Spring Boot

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

Výhodou je:

Skúsenosť s MySQL/MariaDB alebo inou SQL databázou
Skúsenosť s CSS frameworkom Bootstrap

Použitie MySQL a Bootstrap bude v kurze popísané, ale nebudú rozoberané do detailov.

Motivácia

V lekciách kurzu Spring Boot pre začiatočníkov sme si vytvorili aplikáciu kompletne len v Spring Boot. V minulosti sa aplikácie naozaj takto tvorili a doteraz sa nejaké aplikácie takto aj tvoria, hlavne tie, ktoré sú zamerané na články (napr. ITnetwork takto funguje).

V praxi sa dnes ale na webe používa množstvo aplikácií, ktoré sú naozaj skôr aplikáciami než webovými stránkami s článkami, napr. Spotify alebo Google Docs. Od takej aplikácie čaká používateľ skôr funkčnosť ako majú napríklad desktopové aplikácie bežiace v systéme Windows a nie ako webové stránky, kde sa celá stránka prenačíta vždy, keď sa na niečo klikne. Preto sa dnes väčšina aplikácií takto už neprogramuje.

Aplikácia s API serverom a klientom v JavaScripte

Moderné aplikácie sú rozdelené na 2 časti:

API server
Tučný klient (náš bude v JavaScripte a pobeží vo webovom prehliadači, ale mohlo by sa rovnako jednať aj o mobilnú aplikáciu)

API databáza filmov

Našim cieľom bude vytvoriť jednoduché backendové API pre správu databázy filmov. Dáta o filmoch budeme môcť pridávať, upravovať alebo mazať a samozrejme si ich aj prezerať. Práve API sú najčastejšie typy projektov v Java Spring. 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, po slovensky aplikačné programové rozhranie. Je to všeobecne čokoľvek, čo umožňuje jednotlivým častiam softvéru komunikovať medzi sebou. Ide 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 komponent správne fungoval v rámci ostatných komponentov.

API si môžeme predstaviť ako č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čidla na doske) odovzdá to, čo vodič (jeden komponent) chce inému komponentu (motoru). A návod k autu je ako API dokumentácia, kde sú jednotlivé metódy (tlačidlá) popí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 dve časti aplikácie (webová stránka si doťahuje zo servera potrebné dáta pomocou AJAX dotazu) alebo dve 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ží nový film. 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-shopmi beží na stránkach Českej národnej banky. Konkrétne na tejto adrese

Na adrese sú dostupné kurzy mien pre aktuálny deň. Nejde ale o žiadnu HTML stránku, ale o surové dáta vo formáte CSV. Webové API totiž nie sú určené pre ľudí, ale pre programy. Výstup tohto 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,
GraphQL 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 kurzu to sú zvislítka - |, na klávesnici AltGr + W). 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 – URL pri používaní SOAPu 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, 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.

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 SOAPu je oveľa stručnejšie a teda efektívnejšie. Aj napriek svojej stručnosti obsahuje každá požiadavka 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.

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.

API našej aplikácie

Pre našu budúcu databázovú aplikáciu použijeme práve RESTful API, a to z vyššie uvedených dôvodov (jednoduchosť, stručnosť) a taktiež preto, že potrebujeme nad filmami 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ľ spomenieme len to, že je vhodný pre webové prehliadače, ale je ľahko čitateľný aj človekom.

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 cesty. Pre našu prvú tabuľku, ktorá bude obsahovať dáta o filmoch, budeme v našej aplikácii neskôr používať tieto cesty (výraz (id) vždy nahradíme príslušným identifikátorom):

POST

Pre POST požiadavku (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áza si vytvorí 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)

Pút

Pre PUT požiadavku (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úpime na adresu:

/api/movies/(id)

JSON

Už sme uviedli, že RESTful API používa prevažne formát JSON. Pozrime sa teda na jeho podstatu.

JSON (skratka za JavaScript Object Notation) je formát používaný na uchovávanie dát aj na komunikáciu 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, len s niekoľkými obmedzeniami. Mená vlastností musia 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 je krátka ukážka formátu JSON reprezentujúca hudobníka, jeho hudobnú skupinu a jej albumy:

[
    {
        "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..."
        ]
    }
]

To je pre dnešnú lekciu všetko.

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

Užívateľské hodnotenie:

Ešte nikto nehodnotil, buď prvý!

Aktivity