Lekce 2 - REST API v Java Spring Boot - SOAP, GraphQL, REST a JSON
V minulé lekci, REST API v Java Spring Boot - Úvod do webových API, jsme si vysvětlili, proč se moderní aplikace vytvářejí s pomocí API serveru a jak takový server funguje.
V dnešním Java Spring Boot tutoriálu si představíme různé druhy API, konkrétně REST API, SOAP, GraphQL a formát JSON. Tím se připravíme na projekt databáze filmů, který budeme v tomto kurzu vyvíjet.
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:
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
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 se píší pomocí AltGr + W). Častěji se
ale používají středníky ;
. 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 (viz dále) je SOAP spíše
procedurální (REST je orientovaný na data). To se projevuje
i ve způsobu volání API. URL při používání SOAP bude typicky obsahovat
nějaké sloveso, na rozdíl od REST, 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.
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á.
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 SOAP 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.
API naší aplikace
Pro naši budoucí databázovou aplikaci použijeme právě RESTful API. Učiníme tak 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 REST navržené. Dalším důvodem je, že i když REST podporuje mnoho formátů, převládá používání formátu JSON.
Formát JSON
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ů (složené závorky {}
) a polí
(hranaté závorky []
) 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í film Star Wars VI:
{ "_id": "640471c9b80ed070c5425fbc", "name": "Star Wars VI", "year": 1983, "directorID": "64047109b80ed070c5425fb8", "actorIDs": [ "64047e10b3201657ed2b5977" ], "genres": [ "sci-fi" ], "isAvailable": true, "dateAdded": "2023-03-05T10:41:13.608Z", "__v": 0, "director": { "_id": "64047109b80ed070c5425fb8", "name": "James Francis Cameron" }, "actors": [ { "_id": "64047e10b3201657ed2b5977", "name": "Dwayne Johnson" } ] }
Vidíme zde jeden hlavní objekt definovaný pomocí
{}
, který reprezentuje film a obsahuje spoustu
vlastností. Řetězce jsou v uvozovkách, čísla píšeme bez
nich. Několik vlastností obsahuje buď další objekt
zapsaný opět pomocí {}
(režisér director
) nebo
pole zapsané hranatými závorkami []
(ID herců
ve filmu actorIDs
).
JSON je vhodný pro webové prohlížeče, ale je lehce čitelný i člověkem.
Dokumentace k API
Náš server v Java Spring musí poskytovat přesně to API, se kterým umí pracovat daný klient. V našem případě je to API z kurzu Node.js, jehož rozhraní je kompletně popsané v lekci Dokumentace k Node.js API. Na tuto dokumentaci se nyní můžete podívat. Naše práce se bude neustále točit okolo tohoto dokumentu, aby naše endpointy měly správné adresy a přijímaly a odesílaly JSON ve správném formátu.
Endpointy jsou vyústění našeho API, se kterými se dá zvenku komunikovat.
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í URL adresy. Např. pro práci s daty o filmech budeme podle dané dokumentace později používat tyto adresy:
POST
Pro vytvoření nového filmu nám klient pošle POST požadavek (vytvoření, odpovídá CREATE metodě CRUD) na adresu:
/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 seznam všech filmů bude klient posílat na náš server GET požadavky (čtení, odpovídá READ metodě CRUD) na adresu:
/api/movies
A pro jeden konkrétní film:
/api/movies/(id)
Výraz (id)
vždy nahradíme identifikátorem daného filmu.
PUT
Pro PUT požadavek upravující daný film (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í klient na adresu:
/api/movies/(id)
To je pro dnešní lekci vše.
V příští lekci, REST API v Java Spring Boot - Angular/React projekt, si zprovozníme javascriptového klienta, kterého budeme později využívat ke komunikaci s naším Spring API.