3. diel - Webová API - SOAP, GraphQL, REST a formát JSON Nové

V minulej lekcii, Úvod do REST API a moderných webových aplikácií, sme si vysvetlili, prečo sa moderné aplikácie vytvárajú pomocou API servera a ako taký server funguje.

V dnešnom tutoriále praktického testovania projektov si predstavíme rôzne druhy API, konkrétne REST API, SOAP, GraphQL a formát JSON. Tým sa pripravíme na projekt databázy faktúr, ktorý budeme v tomto kurze testovať.

Druhy webových API

Na webe existuje niekoľko rozšírených spôsobov komunikácie. Sú to:

• jednoduchá API,
• API pomocou protokolu SOAP,
• API pomocou architektúry REST,
• GraphQL od Facebooku.

Jednoduchá API

CSV API sme si už predstavili na ukážke s kurzami ČNB:

27.12.2024 #250
country|currency|amount|code|exchange_rate
Australia|dollar|1|AUD|15,027
Brazil|real|1|BRL|3,900
Bulgaria|lev|1|BGN|12,886
China|renminbi|1|CNY|3,309
Denmark|krone|1|DKK|3,379
EMU|euro|1|EUR|25,205
Philippines|peso|100|PHP|41,595
Hong Kong|dollar|1|HKD|3,112
India|rupee|100|INR|28,256
Indonesia|rupiah|1000|IDR|1,488
Iceland|krone|100|ISK|17,371
Israel|new shekel|1|ILS|6,570
Japan|yen|100|JPY|15,307
South Africa|rand|1|ZAR|1,291
Canada|dollar|1|CAD|16,802
South Korea|won|100|KRW|1,639
Hungary|forint|100|HUF|6,127
Malaysia|ringgit|1|MYR|5,402
Mexico|peso|1|MXN|1,192
IMF|SDR|1|XDR|31,503
Norway|krone|1|NOK|2,128
New Zealand|dollar|1|NZD|13,622
Poland|zloty|1|PLN|5,895
Romania|leu|1|RON|5,063
Singapore|dollar|1|SGD|17,783
Sweden|krone|1|SEK|2,196
Switzerland|franc|1|CHF|26,821
Thailand|baht|100|THB|71,045
Turkey|lira|100|TRY|68,723
USA|dollar|1|USD|24,157
United Kingdom|pound|1|GBP|30,337

Položky sú na jednotlivých riadkoch a hodnoty sú oddelené nejakým špeciálnym znakom (v CSV s menami kurzu to sú zvislítka - |, na klávesnici sa píšu pomocou AltGr + W). Častejšie sa ale používajú bodkočiarky ;. Na jednoduché API je možné použiť aj formát XML alebo JSON.

Jednoduchá API typicky ponúka len nejaký zoznam dát na stiahnutie, napríklad počasie podľa mesta. Neumožňujú zložitejšiu manipuláciu s dátami.

SOAP

Skratka SOAP znamená Simple Object Access Protocol. Správy posielané pomocou protokolu SOAP sú obvykle založené na XML (čo je značkovací jazyk podobný HTML). Oproti architektúre REST (viď ďalej) je SOAP skôr procedurálna (REST je orientovaný na dáta). To sa prejavuje aj v spôsobe volania API. URL pri používaní SOAP bude typicky obsahovať nejaké sloveso, na rozdiel od REST, kde bude typicky nejaké podstatné meno (v našom prípade to budú podstatné mená persons a invoices, ale o tom neskôr). Jedným z najznámejších použití protokolu SOAP u nás je odosielanie tržieb pri Elektronickej evidencii tržieb (EET).

SOAP požiadavka na zaevidovanie EET tržby bez dlhej hlavičky, ktorú vypustíme, vyzerá takto:

<soap:Body wsu:Id="id-16FE2A6FC1AFE42BE9146412186273614">
    <Sales>
        <Header send_date="2016-09-19T19:06:37+01:00" first_submission="false" message_uuid="9edeb22b-4234-4047-869c-3a76f86c20d3"/><Data total_sales="34113.00" deducted_settlement="679.00" travel_service="5460.00" tax1="-172.39" tax2="-530.73" tax3="975.65" sales_date="2016-01-05T00:30:12+01:00" taxpayer_vat_id="CZ00000019" cash_register_id="/5546/RO24" establishment_id="273" serial_number="0/6460/ZQ42" used_goods1="784.00" used_goods2="967.00" used_goods3="189.00" mode="0" intended_deducted_settlement="324.00" tax_base1="-820.92" tax_base2="-3538.20" tax_base3="9756.46" non_vat_base="3036.00"/>
        <ControlCodes>
            <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>
        </ControlCodes>
    </Sales>
</soap:Body>

SOAP API bohužiaľ nie sú príliš jednoduché a to aj napriek tomu, že majú v názve slovo Simple. Používajú sa skôr v štátnej sfére a finančníctve na robustné projekty a nie sú častou voľbou pre klasické aplikácie.

GraphQL

Pre predstavu, že existujú aj iné aplikačné rozhrania na komunikáciu na webe, si ukážeme ešte GraphQL. To vytvoril a spopularizoval Facebook. GraphQL používa na reprezentáciu informácií koncept sociálnych grafov s vrcholmi a hranami (ako v teórii grafov). Vrcholy sú objekty ako používateľ, fotka, stránka alebo komentár. Hrany sú potom spojenie medzi objektmi ako napríklad komentáre pod fotkou.

Ukážkový dotaz nižšie získa užívateľa s id: "10", jeho meno, email a priateľov, pre ktorých získa ich mená:

{
  user(id: "10") {
    name
    email
    friends {
      name
    }
  }
}

GraphQL využijeme v prípade, keď je otázky zložité formalizovať a treba si pri každej otázke povedať, čo presne nás zaujíma.

REST

REST je v súčasnej dobe veľmi obľúbená architektúra rozhrania. Je to skratka z REpresentational State Transfer – pojmu, ktorý zaviedol vo svojej dizertačnej práci Roy Fielding. To je jeden zo spoluautorov protokolu HTTP, preto neprekvapí, že REST tento protokol používa. REST implementuje štyri základné CRUD operácie. Tieto operácie sú vytvoriť (Create), čítať (Read), zmeniť (Update) a zmazať (Delete). V HTTP protokole im zodpovedajú metódy:

• GET (prečítať),
• POST (vytvoriť),
• PUT (upraviť),
• DELETE (zmazať).

Práve používanie rôznych HTTP metód je základným princípom REST API. Napríklad by sme nemali odstraňovať dáta cez klasickú GET požiadavku, ktorú používame, keď sa snažíme otvoriť nejakú stránku.

Vďaka štyrom spomínaným metódam je REST rozhranie jednoduché na pochopenie a na používanie. Oproti SOAP je oveľa stručnejšie a teda efektívnejšie. Aj napriek svojej stručnosti každá požiadavka obsahuje všetky informácie potrebné na jeho vybavenie, a server teda nemusí držať žiadny stav (je stateless). Z toho okrem iného vyplýva, že pokiaľ aplikácia potrebuje nejaký stav, musí ho držať klient.

API, ktoré používa rozhranie REST, sa označuje ako RESTful.

API našej aplikácie

V našej databázovej aplikácii budeme testovať funkčnosť práve RESTful API. V aplikácii je použité z vyššie uvedených dôvodov (jednoduchosť, stručnosť) a tiež preto, že potrebujeme nad faktúrami testovať operácie, pre ktoré je REST navrhnuté. Ďalším dôvodom je, že aj keď REST podporuje mnoho formátov, prevláda používanie formátu JSON.

Formát JSON

JSON (skratka odvodená z JavaScript Object Notation) je formát používaný na uchovávanie dát aj na komunikáciu na webe. Pokiaľ poznáte jazyk JavaScript, bude vám syntax JSON povedomá, pretože z neho vychádza. Pre definíciu objektov používame zložené zátvorky {}, pre pole hranaté zátvorky []. Mená vlastností objektov musia byť vždy v dvojitých úvodzovkách a sú povolené iba jednoduché dáta – žiadne výpočty ani volanie funkcií. JSON tiež nesmie obsahovať žiadne komentáre.

Tu je krátka ukážka formátu JSON reprezentujúca faktúru v našej aplikácii databázy faktúr:

{
  "invoiceNumber": 2023001,
  "seller": {
    "name": "John Snow",
    "identificationNumber": "123456789",
    "taxNumber": "EU123456789",
    "accountNumber": "123456700",
    "bankCode": "0100",
    "iban": "EU000123456700",
    "telephone": "111 222 333",
    "mail": "snow@gmail.com",
    "street": "7 Wall Street",
    "zip": "16000",
    "city": "Northern Kingdom",
    "country": "CZECHIA",
    "note": "Wolf",
    "_id": 1
  },
  "buyer": {
    "name": "ICTdemy",
    "identificationNumber": "05861381",
    "taxNumber": "EU05861381",
    "accountNumber": "123456789",
    "bankCode": "5500",
    "iban": "EU000123456789",
    "telephone": "123 123 123",
    "mail": "redaction@ictdemy.com",
    "street": "290/16 Charles Square",
    "zip": "12000",
    "city": "Prague",
    "country": "CZECHIA",
    "note": "The largest IT academy in the Czech Republic.",
    "_id": 3
  },
  "issued": "2023-07-23",
  "dueDate": "2023-07-30",
  "product": "Article",
  "price": 100,
  "vat": 21,
  "note": "Creating educational articles",
  "_id": 4
}

Vidíme tu jeden hlavný objekt definovaný pomocou {}, ktorý reprezentuje faktúru a obsahuje množstvo vlastností. Reťazce sú v úvodzovkách, čísla píšeme bez nich. Hlavný objekt obsahuje ďalšie objekty (odberateľ buyer a dodávateľ seller) zapísaný opäť pomocou {}.

JSON je vhodný pre webové prehliadače, ale je ľahko čitateľný aj človekom.

Dokumentácia k API

Náš server v Python Django musí poskytovať presne to API, s ktorým vie pracovať daný klient. V našom prípade je to API z kurzu Node.js, ktorého rozhranie je kompletne popísané v lekcii API dokumentácie k databáze faktúr. Na túto dokumentáciu sa teraz môžete pozrieť. Naša práca sa bude neustále točiť okolo tohto dokumentu, aby naše endpointy mali správne adresy a prijímali a odosielali JSON v správnom formáte.

Endpointy sú vyústenia nášho API, s ktorými sa dá zvonku komunikovať.

Pri odosielaní požiadavky pomocou RESTful API nám k tomu, aby bola požiadavka spracovaná, tak ako potrebujeme, napomáha správne použitie URL adresy. Napríklad pre prácu s osobami budeme podľa danej dokumentácie neskôr používať adresy popísané v nasledujúcich kapitolách.

POST

Pre vytvorenie novej osoby nám klient pošle POST požiadavku (vytvorenie, zodpovedá CREATE metóde CRUD) na adresu:

/api/persons

Nie je potrebné zadávať id osoby, ide o vytvorenie položky v databáze, databáza si vytvorí id sama.

GET

Pre zoznam všetkých osôb bude klient posielať na náš server GET požiadavky (čítanie, zodpovedá READ metóde CRUD) na adresu:

/api/persons

A pre jednu konkrétnu osobu:

/api/persons/(id)

Výraz (id) vždy nahradíme identifikátorom daného filmu.

PUT

Pre PUT požiadavku upravujúcu danú osobu (editácia, zodpovedá UPDATE metóde CRUD) bude adresa nasledujúca:

/api/persons/(id)

DELETE

A pre DELETE požiadavku (zmazanie, zodpovedá DELETE metóde CRUD) pristúpi klient na adresu:

/api/persons/(id)

To je pre dnešnú lekciu všetko.

V nasledujúcom kvíze, Kvíz - Úvod do testovania, REST API, webová API, si vyskúšame nadobudnuté skúsenosti z predchádzajúcich lekcií.