Klient a server¶
Jak jsme si vysvětlili v předešlé kapitole, API je dohoda mezi dvěma stranami o tom, jak si mezi sebou budou povídat. Těmto stranám se říká klient a server.
Server je ta strana, která má zajímavé informace, nebo něco zajímavého umí, a umožňuje ostatním na internetu, aby toho využili. V našem počátečním příkladu by se v širším slova smyslu dal jako server označit ČHMÚ, jenž poskytuje API ke svým předpovědím počasí, nebo ČNB, která poskytuje API ke svému kurzovnímu lístku. Ve skutečnosti je server program, který donekonečna běží na nějakém počítači oné instituce a je připraven všem ostatním na internetu odpovídat na požadavky.
Klient je program, který posílá požadavky na server a z odpovědí se snaží poskládat něco užitečného. Klient je tedy mobilní aplikace s mráčky a sluníčky nebo náš prohlížeč, v němž jsme si otevírali kurzovní lístek ČNB. Je to ale i ten robot, který za Heureku načítá informace o zboží v e-shopech.
Todo
obrazek server/klient, jeden server ktery poskytuje data a dva klienti, robot a clovek, jak to ctou, udelat tam jasne request response
Obecný klient¶
Mobilní aplikace na počasí je klient, který někdo vytvořil pro jeden konkrétní úkol. Takový většinou umí pracovat jen s jedním konkrétním API. To je užitečné, pokud chceme akorát vědět jaké je počasí, ale už méně, pokud si chceme zkoušet práci s více API zároveň. Proto existují obecní klienti.
Prohlížeč jako obecný klient¶
Pokud z API chceme pouze číst a ono nevyžaduje žádné přihlašování, můžeme jej vyzkoušet i v prohlížeči, jako by to byla webová stránka. To jsme si ostatně už dříve předvedli v případě kurzovního lístku ČNB. Pokud v prohlížeči přejdeme na odkaz Stažení v textovém formátu, uvidíme odpověď z API serveru.
Zkusme jiný příklad. OMDb je API, které poskytuje informace o filmech. Po registraci nám bude na e-mail zaslán tajný klíč, se kterým můžeme na API zdarma posílat 1000 požadavků denně.
Nyní zkusme v API najít seriál Westworld. Podle dokumentace OMDb můžeme složit následující adresu, pokud hledáme slovo westworld v názvu titulu:
https://www.omdbapi.com/?t=westworld&apikey=abcd123
Místo abcd123 má být samozřejmě tajný API klíč, který nám přišel e-mailem. Zkusíme adresu otevřít v prohlížeči:
Smyslem API je vracet odpovědi pro stroje, takže dostaneme změť písmenek, která se člověku nečte zrovna nejlépe. Něco v ní ale vidět lze - není těžké rozluštit, že seriál je drama a hraje v něm Evan Rachel Wood.
Obecný klient v příkazové řádce: curl¶
Pokud se k API budeme potřebovat přihlásit nebo s ním zkoušet dělat složitější věci než jen čtení, nebude nám prohlížeč stačit.
Proto je dobré se naučit používat program curl. Spouští se v příkazové řádce a je to švýcarský nůž všech, kteří se pohybují kolem webových API. Je tak používaný a významný, že za něj jeho autor Daniel Stenberg dostal v roce 2017 ocenění z rukou švédského krále.
Instalace curl¶
Varování
Pokud materiály procházíte v rámci workshopu a curl jste si už nainstalovali v rámci přípravy, můžete tuto sekci přeskočit.
Je dost možné, že curl je již přímo v našem systému (většina Linuxů, macOS, Windows 10) a není potřeba nic instalovat. Necháme program vypsat svou verzi, čímž ověříme, jestli funguje:
$ curl --version
curl 7.54.0 (x86_64-apple-darwin18.0) libcurl/7.54.0 LibreSSL/2.6.5 zlib/1.2.11 nghttp2/1.24.1
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smb smbs smtp smtps telnet tftp
Features: AsynchDNS IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz HTTP2 UnixSockets HTTPS-proxy
Vypíše-li se verze programu curl, jak je na příkladu výše, máme hotovo. Program curl je v systému a je funkční. Můžeme instalaci přeskočit. Pokud se ale místo verze vypíše něco v tom smyslu, že příkaz ani program curl neexistuje, pak je potřeba curl doinstalovat.
Instalujeme standardní cestou přes správce balíčků. V distribucích Debian nebo Ubuntu takto:
$ sudo apt-get install curl
V distribuci Fedora takto:
$ sudo dnf install curl
Nakonec necháme program vypsat svou verzi, čímž ověříme, jestli funguje:
$ curl --version
Pokud máme Git for Windows nebo Cygwin, je velká šance, že curl už máme, jen jej musíme spouštět ze speciálního terminálu poskytovaného těmito nástroji. Otevřeme tento speciální terminál a necháme program vypsat verzi:
$ curl --version
Vypíše-li se verze programu curl, máme hotovo a můžeme instalaci přeskočit. Pokud se ale místo verze vypíše něco v tom smyslu, že příkaz ani program curl neexistuje, pak je potřeba curl doinstalovat. Máme-li Chocolatey, mělo by stačit v příkazové řádce spustit následující:
$ choco install curl
Poté necháme curl vypsat svou verzi:
$ curl --version
Vypíše-li se verze programu curl, máme hotovo a můžeme instalaci přeskočit. Pokud se ale místo verze vypíše něco v tom smyslu, že choco nebo curl neexistují, musíme curl stáhnout a nainstalovat ručně.
Na stránkách programu najdeme verzi pro Windows a podle typu našich Windows (Jak zjistit, zda máme 32bitové, nebo 64bitové?) vybereme odpovídající verzi. Po rozbalení dostaneme spustitelný soubor curl.exe, který přidáme do systémové cesty. Pokud přidávat programy do systémové cesty neumíme, pro účely tohoto návodu postačí, pokud soubor curl.exe dáme do té složky, ze které jej budeme chtít spouštět. Nakonec necháme program vypsat svou verzi, čímž ověříme, jestli funguje:
$ curl --version
Příklady s curl¶
Nyní můžeme curl vyzkoušet:
$ curl "https://www.cnb.cz/cs/financni-trhy/devizovy-trh/kurzy-devizoveho-trhu/kurzy-devizoveho-trhu/denni_kurz.txt"
Když příkaz zadáme a spustíme, říkáme tím programu curl, že má poslat požadavek na uvedenou adresu a vypsat to, co mu ČNB pošle zpět.
$ curl "https://www.cnb.cz/cs/financni-trhy/devizovy-trh/kurzy-devizoveho-trhu/kurzy-devizoveho-trhu/denni_kurz.txt"
10.05.2019 #89
země|měna|množství|kód|kurz
Austrálie|dolar|1|AUD|16,023
Brazílie|real|1|BRL|5,796
Bulharsko|lev|1|BGN|13,157
Čína|žen-min-pi|1|CNY|3,359
Dánsko|koruna|1|DKK|3,446
EMU|euro|1|EUR|25,730
Filipíny|peso|100|PHP|43,823
Hongkong|dolar|1|HKD|2,920
Chorvatsko|kuna|1|HRK|3,473
Indie|rupie|100|INR|32,737
Indonesie|rupie|1000|IDR|1,600
Island|koruna|100|ISK|18,781
Izrael|nový šekel|1|ILS|6,433
Japonsko|jen|100|JPY|20,876
Jižní Afrika|rand|1|ZAR|1,610
Kanada|dolar|1|CAD|17,005
Korejská republika|won|100|KRW|1,942
Maďarsko|forint|100|HUF|7,953
Malajsie|ringgit|1|MYR|5,510
Mexiko|peso|1|MXN|1,194
MMF|ZPČ|1|XDR|31,708
Norsko|koruna|1|NOK|2,620
Nový Zéland|dolar|1|NZD|15,112
Polsko|zlotý|1|PLN|5,990
Rumunsko|leu|1|RON|5,406
Rusko|rubl|100|RUB|35,081
Singapur|dolar|1|SGD|16,812
Švédsko|koruna|1|SEK|2,379
Švýcarsko|frank|1|CHF|22,619
Thajsko|baht|100|THB|72,557
Turecko|lira|1|TRY|3,738
USA|dolar|1|USD|22,915
Velká Británie|libra|1|GBP|29,835
Poznámka
Pokud používáte Windows, je velká šance, že se vám při zkoušení příkladu výše zobrazí špatně diakritika. Nic si z toho nedělejte, příkazová řádka na Windows má jiné kódování textu než zbytek světa. Důležité je, pokud vidíte seznam kurzů měn.
Totéž můžeme udělat i s adresou, která nám vracela informace z OMDb:
$ curl "https://www.omdbapi.com/?t=westworld&apikey=abcd123"
{"Title":"Westworld","Year":"2016–","Rated":"TV-MA","Released":"02 Oct 2016","Runtime":"62 min","Genre":"Drama, Mystery, Sci-Fi, Western","Director":"N/A","Writer":"N/A","Actors":"Evan Rachel Wood, Thandie Newton, Jeffrey Wright, Ed Harris","Plot":"Set at the intersection of the near future and the reimagined past, explore a world in which every human appetite can be indulged without consequence.","Language":"English","Country":"USA","Awards":"Nominated for 3 Golden Globes. Another 29 wins & 75 nominations.","Poster":"https://m.media-amazon.com/images/M/MV5BNThjM2Y3MDUtYTIyNC00ZDliLWJlMmItNWY1N2E5NjhmMGM4XkEyXkFqcGdeQXVyNjU2ODM5MjU@._V1_SX300.jpg","Ratings":[{"Source":"Internet Movie Database","Value":"8.8/10"}],"Metascore":"N/A","imdbRating":"8.8","imdbVotes":"334,034","imdbID":"tt0475784","Type":"series","totalSeasons":"3","Response":"True"}
Program curl toho samozřejmě umí více a proto je tak užitečný, ale to si ukážeme později.
Obecný klient jako aplikace¶
Příkazová řádka je sice velmi mocný a univerzální nástroj, ale není vždy nejpříjemnější na každodenní používání. Následující programy jsou obecní klienti, na které se dá normálně klikat:
Postman - zdarma, pro všechny operační systémy
RESTClient - zdarma, pro všechny operační systémy, doplněk do prohlížeče Firefox
Paw - dražší, ale velmi vyladěný profesionální nástroj pro macOS
Stejně jako v případě práce s Gitem i zde platí, že si můžeme nainstalovat sebekrásnější program, ale pokud budeme potřebovat vyřešit nějaký problém, dostaneme rady většinou v podobě curl příkazu.
Stejně jako u Gitu i curl má velmi složitý systém paramterů a přepínátek, stejně jako u Gitu jim málokdo dokonale rozumí, ale stejně jako u Gitu je to přesně to, co lidé nakonec používají jako společný jazyk, do kterého zapisují a přes který sdílí řešení problémů - například na StackOverflow.
Klient pro konkrétní úkol¶
Obecného klienta musí ovládat člověk. To je přesně to, co potřebujeme, když si chceme nějaké API vyzkoušet, ale celý smysl API je v tom, aby je programy mohly využívat automaticky.
K tomu slouží klienti, které někdo vytvořil pro konkrétní úkol. Jak už jsme si řekli, je to třeba ona aplikace pro zobrazování počasí, která je schopna si data z API přečíst úplně sama. Aby to ale mohla udělat, musí odpověď ze serveru přijít ve formátu, kterému bude rozumět. A o tom, jak to celé funguje, bude následující kapitola.