Lekce 3 - Webová API - SOAP, GraphQL, REST a formát JSON

V minulé lekci, Úvod do REST API a moderních webových aplikací, jsme si vysvětlili, proč se moderní aplikace vytvářejí pomocí API serveru a jak takový server funguje.

V dnešním tutoriálu praktického testování projektů 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 faktur, který budeme v tomto kurzu testovat.

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:

27.12.2024 #250
země|měna|množství|kód|kurz
Austrálie|dolar|1|AUD|15,027
Brazílie|real|1|BRL|3,900
Bulharsko|lev|1|BGN|12,886
Čína|žen-min-pi|1|CNY|3,309
Dánsko|koruna|1|DKK|3,379
EMU|euro|1|EUR|25,205
Filipíny|peso|100|PHP|41,595
Hongkong|dolar|1|HKD|3,112
Indie|rupie|100|INR|28,256
Indonesie|rupie|1000|IDR|1,488
Island|koruna|100|ISK|17,371
Izrael|nový šekel|1|ILS|6,570
Japonsko|jen|100|JPY|15,307
Jižní Afrika|rand|1|ZAR|1,291
Kanada|dolar|1|CAD|16,802
Korejská republika|won|100|KRW|1,639
Maďarsko|forint|100|HUF|6,127
Malajsie|ringgit|1|MYR|5,402
Mexiko|peso|1|MXN|1,192
MMF|ZPČ|1|XDR|31,503
Norsko|koruna|1|NOK|2,128
Nový Zéland|dolar|1|NZD|13,622
Polsko|zlotý|1|PLN|5,895
Rumunsko|leu|1|RON|5,063
Singapur|dolar|1|SGD|17,783
Švédsko|koruna|1|SEK|2,196
Švýcarsko|frank|1|CHF|26,821
Thajsko|baht|100|THB|71,045
Turecko|lira|100|TRY|68,723
USA|dolar|1|USD|24,157
Velká Británie|libra|1|GBP|30,337

Položky jsou na jednotlivých řádcích a hodnoty jsou oddělené nějakým speciálním znakem (v CSV s kurzy měn to jsou svislítka – |, na klávesnici se píšou 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ízejí jen nějaký seznam dat ke stažení, například 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 architektuře REST (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, kdežto u architektury REST to bude typicky nějaké podstatné jméno (v našem případě podstatná jména persons a invoices, 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á, 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 např. 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, e-mail 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 kdy 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 odvozená 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í i na používání. Oproti SOAP je mnohem stručnější, a tedy efektivnější. I přes svoji stručnost každý požadavek obsahuje 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

V naší databázové aplikaci budeme testovat funkčnost právě RESTful API. V aplikaci je použito z výše uvedených důvodů (jednoduchost, stručnost) a také proto, že potřebujeme nad fakturami testovat 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 odvozená z JavaScript Object Notation) je formát používaný k uchovávání dat i ke komunikaci na webu. Pokud znáte jazyk JavaScript, bude vám syntaxe JSON povědomá, protože z něj vychází. Pro definici objektů používáme složené závorky {}, pro pole hranaté závorky []. Jména vlastností objektů musí být vždy v dvojitých uvozovkách a jsou povolena pouze jednoduchá data – žádné výpočty ani volání funkcí. JSON také nesmí obsahovat žádné komentáře.

Zde je krátká ukázka formátu JSON reprezentující fakturu v naší aplikaci databáze faktur:

{
  "invoiceNumber": 2023001,
  "seller": {
    "name": "Jan Novák",
    "identificationNumber": "14025582",
    "taxNumber": "CZ14025582",
    "accountNumber": "12345678",
    "bankCode": "5500",
    "iban": "CZ00123456789",
    "telephone": "+420 900 900 900",
    "mail": "jan.novak@seznam.cz",
    "street": "Tichá 288, 742 74 Tichá",
    "zip": "744 01",
    "city": "Frenštát pod Radhoštěm",
    "country": "CZECHIA",
    "note": "Gilgamesh",
    "_id": 1
  },
  "buyer": {
    "name": "ITnetwork s.r.o.",
    "identificationNumber": "05861381",
    "taxNumber": "CZ05861381",
    "accountNumber": "123456789",
    "bankCode": "5500",
    "iban": "CZ000123456789",
    "telephone": "+420 123 123 123",
    "mail": "redakce@itnetwork.cz",
    "street": "Karlovo náměstí 290/16, Nové Město (Praha 2)",
    "zip": "120 00",
    "city": "Praha",
    "country": "CZECHIA",
    "note": "Největší IT akademie v Česku.",
    "_id": 4
  },
  "issued": "2023-07-23",
  "dueDate": "2023-07-30",
  "product": "Článek",
  "price": 100,
  "vat": 21,
  "note": "Tvorba výukových článků",
  "_id": 4
}

Vidíme zde jeden hlavní objekt definovaný pomocí {}, který reprezentuje fakturu a obsahuje spoustu vlastností. Řetězce jsou v uvozovkách, čísla píšeme bez nich. Hlavní objekt obsahuje další objekty (odběratel buyer a dodavatel seller) zapsaný opět pomocí {}.

JSON je vhodný pro webové prohlížeče, ale je lehce čitelný i člověkem.

Dokumentace k API

Náš server v Python Djangu 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 API dokumentace k databázi faktur. 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, s nimiž 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říklad pro práci s osobami budeme podle dané dokumentace později používat adresy popsané v následujících kapitolách.

POST

Pro vytvoření nové osoby nám klient pošle POST požadavek (vytvoření, odpovídá CREATE metodě CRUD) na adresu:

/api/persons

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

GET

Pro seznam všech osob bude klient posílat na náš server GET požadavky (čtení, odpovídá READ metodě CRUD) na adresu:

/api/persons

A pro jednu konkrétní osobu:

/api/persons/(id)

Výraz (id) vždy nahradíme identifikátorem dané osoby.

PUT

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

/api/persons/(id)

DELETE

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

/api/persons/(id)

To je pro dnešní lekci vše.

V následujícím kvízu, Kvíz - Úvod do testování, REST API, webová API, si vyzkoušíme nabyté zkušenosti z předchozích lekcí.