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.