2. diel - REST API v Django REST - SOAP, GraphQL, REST a JSON Nové

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

V dnešnom Django REST Framework tutoriále 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 filmov, ktorý budeme v tomto Python kurze vyvíjať.

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:

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 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. počasie podľa mesta. Neumožňujú zložitejšiu manipuláciu s dátami.

SOAP

Skratka SOAP znamená S imple O bject A ccess P rotocol. Správy posielané pomocou protokolu SOAP sú obvykle založené na XML (čo je značkovací jazyk podobný HTML). Oproti RESTu (viď ďalej) je SOAP skôr procedurálny (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 bude podstatné meno movies, 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">
    <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žiaľ nie sú príliš jednoduché, hoci 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á otázka nižšie získa užívateľov s id: "10", jeho meno, e-mail 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 kedy si treba 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 odvodená z RE presentational S tate T ransfer – 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ť (C reate), čítať (R ead), zmeniť (U pdate) a zmazať (D elete). 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 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 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

Pre našu budúcu databázovú aplikáciu použijeme práve RESTful API. Urobíme tak z vyššie uvedených dôvodov (jednoduchosť, stručnosť) a tiež preto, že potrebujeme nad filmami vykonávať 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 za Java S cript O bject N otation) je formát používaný na uchovávanie dát aj na komunikáciu na webe. Hoci vychádza z JavaScriptu, používajú ho aj iné jazyky. Jeho syntax je veľmi podobná syntax objektov (zložené zátvorky {}) a polí (hranaté zátvorky []) v JavaScripte, len s niekoľkými obmedzeniami. Mená vlastností musia byť vždy v dvojitých úvodzovkách a sú povolené iba jednoduché dáta - žiadne výpočty ani volanie funkcií. Komentáre nie sú povolené.

Tu je krátka ukážka formátu JSON reprezentujúca 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 tu jeden hlavný objekt definovaný pomocou {}, ktorý reprezentuje film a obsahuje veľa vlastností. Reťazce sú v úvodzovkách, čísla píšeme bez nich. Niekoľko vlastností obsahuje buď ďalší objekt zapísaný opäť pomocou {} (režisér director) alebo pole zapísané hranatými zátvorkami [] (ID hercov vo filme actorIDs).

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

Dokumentácia k API

Náš server v Pythone 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 Dokumentácia k Node.js API. 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. pre prácu s dátami o filmoch budeme podľa danej dokumentácie neskôr používať tieto adresy:

Požiadavka `POST`

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

/api/movies

V tejto požiadavke nie je potrebné zadávať id filmu, ide o vytvorenie položky v databáze, databáza si vytvorí id sama.

Požiadavka `GET`

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

/api/movies

A pre jeden konkrétny film:

/api/movies/(id)

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

Požiadavka `PUT`

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

/api/movies/(id)

Požiadavka `DELETE`

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

/api/movies/(id)

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

V budúcej lekcii, REST API v Django REST - Angular/React projekt , si sprevádzkováme javascriptového klienta, ktorého budeme neskôr využívať na komunikáciu s naším Django REST API.

Absolvované

Označiť lekciu ako neabsolvovanú

Pokračovať vo výuke
REST API v Django REST - Angular/React projekt

Ako sa ti páči článok?

Pred uložením hodnotenia, popíš prosím autorovi, čo je zleZnakov 0 z 50-500

Článok pre vás napísal Max Snítil

Užívateľské hodnotenie:

Ešte nikto nehodnotil, buď prvý!

Aktivity

Najčastejšie vyhľadávané

2. diel - REST API v Django REST - SOAP, GraphQL, REST a JSON Nové

Druhy webových API

SOAP

GraphQL

REST

API našej aplikácie

Formát JSON

Dokumentácia k API

Požiadavka POST

Požiadavka GET

Požiadavka PUT

Požiadavka DELETE

Požiadavka `POST`

Požiadavka `GET`

Požiadavka `PUT`

Požiadavka `DELETE`