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

V predchádzajúcej 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šnej lekcii 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é čiary - |, 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ú zvyčajne založené na XML (čo je značkovací jazyk podobný HTML).

Formát XML

XML (eXtensible Markup Language) je formát určený na štruktúrované ukladanie a výmenu dát. Podobne ako HTML používa značky (tagy) v lomených zátvorkách <>, ale ich názvy si môžeme ľubovoľne definovať. Vďaka tomu potom presne popisujú význam dát. Celý dokument obsahuje jediný koreňový element, do ktorého sú vnorené ďalšie párové značky vytvárajúce hierarchiu. Vnútri týchto značiek môže byť buď text, alebo ďalšie značky. XML nepodporuje výpočty ani spúšťanie kódu – sú povolené iba jednoduché dáta.

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>

Vidíme tu jeden koreňový element <soap:Body>, ktorý tvorí telo SOAP správy. Vnútri sa nachádza element <Sales> a ten má tri podriadené elementy <Header>, <Data> a <ControlCodes>. Hodnoty sa odovzdávajú buď ako atribúty v tvare name="value" (napr. send_date="...") alebo ako vnorené elementy (napr. <pkp>...</pkp>). Každá otvorená značka musí mať uzatvárací náprotivok.

Formát sa používa na výmenu dát medzi systémami, ale zostáva ľahko čitateľný aj pre človeka.

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ý dopyt 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 pri každej otázke si treba 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, dáta by sme nemali odstraňovať cez klasickú požiadavku GET, ktorú používame, keď sa snažíme otvoriť nejakú stránku.

Vďaka štyrom spomínaným metódam je rozhranie REST 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 obsahuje každá požiadavka 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 ak 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. Ak 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": "[email protected]",
    "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": "[email protected]",
    "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 požiadavky GET (čí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 danej osoby.

PUT

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

/api/persons/(id)

DELETE

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

/api/persons/(id)

To je na dnes 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í.

Článok pre vás napísal David Novák

Užívateľské hodnotenie:

12 hlasov

Autor se věnuje vývoji webových aplikací v ASP.NET Core MVC

Aktivity

Najčastejšie vyhľadávané

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

Druhy webových API

Jednoduché API

SOAP

Formát XML

GraphQL

REST

API našej aplikácie

Formát JSON

Dokumentácia k API

POST

GET

PUT

DELETE