Lekce 2 - REST API, SOAP, GraphQL a JSON

V minulé lekci, Úvod do Node.js, jsme si nainstalovali a představili Node.js.

V dnešním Node.js tutoriálu si představíme různé druhy API, konkrétně REST API, SOAP, GraphQL a formát JSON, čímž se připravíme na projekt databáze filmů, který budeme v tomto kurzu vyvíjet.

Projekt databáze filmů

Naším cílem bude vytvořit jednoduché backendové API pro správu databáze filmů. Data o filmech budeme moci přidávat, upravovat nebo mazat a samozřejmě si je i prohlížet. Právě API jsou nejčastější typy projektů v Node.js. K databázi filmů budeme přistupovat pomocí RESTful API a budeme používat formát JSON... Počkat, počkat, co znamenají všechny ty zkratky?

API

API je zkratka pro Application Programming Interface, česky aplikační programové rozhraní. Je to obecně cokoli, co umožňuje jednotlivým částem softwaru komunikovat mezi sebou. Jedná se o souhrn funkcí a procedur, tříd, komunikačních protokolů a dalších nástrojů. Jde o to, aby metody pro komunikaci byly přesně definované. Programátor, který vytváří novou komponentu systému, potom ví (nebo může najít v dokumentaci), jaké postupy může použít, aby jeho komponenta správně fungovala v rámci ostatních komponent.

API si můžeme představit jako číšníka v restauraci, který zajišťuje (a překládá) komunikaci mezi hostem a kuchařem. Nebo jako palubní desku automobilu, která pomocí přesně definovaných metod (tlačítka na desce) předá to, co řidič (jedna komponenta) chce jiné komponentě (motoru). A návod k autu je jako API dokumentace, kde jsou jednotlivé metody (tlačítka) popsané.

Existují grafická API, API pro frameworky a knihovny, API operačních systémů, ale nás budou zajímat hlavně webová API.

Webová API

Webové API definuje, jak spolu komunikují nějaké komponenty po internetu. Typicky se jedná o dvě části aplikace (webová stránka si dotahuje ze serveru potřebná data pomocí AJAX dotazu) nebo dvě různé aplikace (mobilní aplikace si stahuje data z webu). Synonymem může být webová služba. Naše webové API bude umožňovat provádět operace nad databází filmů, např. vyhledá existující film nebo vloží film nový. Webová API samozřejmě nejsou omezená jen na databáze, můžeme přes ně posílat SMS, zjistit aktuální počasí a podobně.

Ukázka webového API

Malinké, ale velmi populární API mezi českými e-shopy běží na stránkách České národní banky. Konkrétně na této adrese.

Jsou zde dostupné kurzy měn pro aktuální den. Nejde ale o žádnou HTML stránku, nýbrž o surová data ve formátu CSV. Webová API totiž nejsou určená pro lidi, ale pro programy. Výstup tohoto API vypadá 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 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. 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 je napíšeme klávesovou zkratkou AltGr + W.

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 je SOAP spíše procedurální (REST je orientovaný na data). To se projevuje i ve způsobu volání - URL při používání SOAPu bude typicky obsahovat nějaké sloveso, na rozdíl od RESTu, 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.

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:

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 SOAPu 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.

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á.

API databáze filmů

Pro naši budoucí databázovou aplikaci použijeme právě RESTful API, a to 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 navržené. Dalším důvodem je, že i když REST podporuje mnoho formátů, převládá používání formátu JSON.

O formátu JSON si ještě dnes něco povíme, zatím zmíníme jen to, že je vhodný pro webové prohlížeče, ale je lehce čitelný i člověkem.

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í cesty. Pro naši první tabulku, která bude obsahovat data o filmech, budeme v naší aplikaci později používat tyto cesty (výraz (id) vždy nahradíme příslušným identifikátorem).

`POST`

Pro POST požadavek (vytvoření, odpovídá CREATE metodě CRUD) bude adresa:

/api/movies

Není potřeba zadávat id filmu, protože jde o vytvoření položky v databázi. Databáze si vytvoří id sama.

`GET`

Pro GET požadavek (čtení, odpovídá READ metodě CRUD) použijeme pro všechny filmy adresu:

/api/movies

A pro jeden konkrétní film:

/api/movies/(id)

`PUT`

Pro PUT požadavek (editace, odpovídá UPDATE metodě CRUD) bude adresa následující:

/api/movies/(id)

`DELETE`

A pro DELETE požadavek (smazání, odpovídá DELETE metodě CRUD) přistoupíme na adresu:

/api/movies/(id)

JSON

Již jsme uvedli, že RESTful API používá převážně formát JSON. Podívejme se tedy na jeho podstatu.

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ů a polí 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í hudebníka, jeho hudební skupinu a její alba:

[
    {
        "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 pro dnešní lekci vše.

V příští lekci, Rozběhnutí projektu a první řádky v Expressu, se seznámíme s knihovnou Express. Projdeme si založení nového projektu a implementujeme si první z metod RESTful API, metodu GET.

Článek pro vás napsal Petr Sedláček

Uživatelské hodnocení:

237 hlasů

Aktivity