Návrh SW Návrh SW
Spouštíme individuální výuku programování! Zaváděcí slevy 799 Kč 599 Kč/60 minut se zkušeným lektorem! Výuka osobně Praha a okolí nebo po Skype celá ČR. O termíny a slevu si pište na [email protected].
Extra 10 % bodů navíc a tričko zdarma při zadání kódu "TRIKO10"

Lekce 2 - REST API, SOAP, GRAPH a JSON

JavaScript Node.js REST API, SOAP, GRAPH a JSON

ONEbit hosting Unicorn College Tento obsah je dostupný zdarma v rámci projektu IT lidem. Vydávání, hosting a aktualizace umožňují jeho sponzoři.

V lekci minulé, Úvod do Node.js, jsme si nainstalovali a představili Node. Dnes bude řeč o různých druzích API a formátu JSON, čímž se připravíme na projekt, který budeme v tomto kurzu vytvářet.

Představení projektu

V tomto kurzu budeme vytvářet jednoduché backendové API pro správu databáze filmů. Budeme moci data o filmech 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.

Pokud si chcete API představit jako něco z běžného života, tak si představte číš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 2 části aplikace (webová stránka si dotahuje ze serveru potřebná data pomocí AJAX dotazu) nebo 2 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 adrese: https://www.cnb.cz/…nni_kurz.txt

Když si adresu otevřete, vypíše se vám kurz měn pro aktuální den. Všimněte si, že se nevygenerovala žádná HTML stránka, ale surová data ve formátu CSV. Webová API totiž nejsou určená pro lidi, ale pro programy. Výstup 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
  • Graph API 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 jednoduchá API se může používat 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, a 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 (viz dále) 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, jak uvidíte 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 by bez dlouhé hlavičky, kterou jsem vypustil, vypadal např. 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. 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 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.

Graph API

Pro představu, že existují i jiná aplikační rozhraní pro komunikaci na webu, si ukážeme ještě Graph API. To vytvořil a zpopularizoval Facebook, který přes něj servíruje velmi rozmanitá data. Facebooku se totiž můžeme zeptat na tolik věcí, že by REST nebo dokonce SOAP požadavky byly velmi nepřehledné. Graph API 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. A data jsou uložena v polích objektů.

Ukázkový dotaz níže se Facebooku ptá na narozeniny, email a město daného uživatele:

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

Graph API 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 naší aplikace

Pro naši 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ím jen to, že je vhodný pro webové prohlížeče a pro nás bude praktický i z důvodu použité databáze - o té si povíme v některém z příštích článků.

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 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, 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ž jsem zmiňoval, že RESTful API používá převážně formát JSON. A co to tedy je?

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, 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 máte krátkou ukázku 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..."
        ]
    }
]

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
Avatar
Jak se ti líbí článek?
2 hlasů
Miniatura
Předchozí článek
Úvod do Node.js
Miniatura
Všechny články v sekci
Node.js
Aktivity (11)

 

 

Komentáře

Děláme co je v našich silách, aby byly zdejší diskuze co nejkvalitnější. Proto do nich také mohou přispívat pouze registrovaní členové. Pro zapojení do diskuze se přihlas. Pokud ještě nemáš účet, zaregistruj se, je to zdarma.

Zatím nikdo nevložil komentář - buď první!