1. diel - ASP.NET Web API - Úvod

Vitajte v kurze o tvorbe webového API filmovej databázy pomocou technológie ASP.NET Core.

Tento kurz nadväzuje na kurz Základy ASP.NET Core MVC, kde sme tvorili aplikácie kompletne len pomocou technológie ASP.NET Core MVC, HTML a CSS. V minulosti sa všetky aplikácie týmto spôsobom naozaj tvorili, dnes ich však už vytláča spôsob nový.

Aplikácia s API serverom a klientom v JavaScripte

V praxi sa totiž na webe používa veľa aplikácií, ktoré sú naozaj skôr aplikáciami, než webovými stránkami s článkami. Zoberme si napríklad také Spotify alebo Google Dokumenty. Od takých aplikácií používateľ čaká skôr správanie ako majú desktopové aplikácie, pri ktorých nemusí čakať na prenačítanie celej stránky po kliknutí na tlačidlo, ako je to pri tradičných webových aplikáciách. Preto sa dnes väčšina aplikácií už takto neprogramuje.

To však neznamená, že by webové aplikácie založené na MVC architektúre nemali na trhu svoje miesto a neoplatí sa ich teda ani učiť vytvárať. Táto technológia sa napríklad hodí na weby zamerané na články (ITnetwork takto funguje) alebo na e-shopy.

Moderné aplikácie sú rozdelené na dve časti:

webový server s databázou a API,
mohutný klient v JavaScripte

V tomto kurze sa zameriame na tú prvú časť, teda tvorbu webového API, a klienta si požičiame z tunajších kurzov na technológie React alebo Angular.

V oboch kurzoch sa programuje klient pre správu databázy filmov. Našou úlohou bude vytvoriť túto databázu spolu s webovým API sprostredkovávajúcim komunikáciu s daným klientom. Nakoniec budeme schopní dáta o filmoch pridávať, upravovať alebo mazať a samozrejme si ich aj prezerať:

Požiadavky na znalosti

Tento projekt je na pomedzí junior/medior, čo sa týka levelu znalostí. V rámci levelu znalostí junior sa predpokladá skôr orientácia v tomto väčšom C# projekte, než že budeš úplne všetkému rozumieť. Pokiaľ by si chcel detailne pochopiť všetok kód, pomôžu ti znalosti v rozsahu medior-level.

Junior-level znalosti

V rámci levelu znalostí junior sa predpokladajú znalosti v tomto rozsahu:

Medior-level znalosti

Ak by ste chceli detailne pochopiť všetok kód, pomôžu vám ešte nasledujúce znalosti, ale počítajte s vyššou časovou náročnosťou:

Debugging
Základná konštrukcia jazyka JavaScript
Bootstrap
Git napr. pre prepínanie medzi commitmi (verziami aplikácie) pri analýze posledných zmien,
UML
Dependency injection a softvérovej architektúry

Teraz si však povieme, čo to API vlastne je a aké máme jeho druhy.

API

API je skratka pre Application Programming Interface, česky aplikačné programové rozhranie. Je to všeobecne čokoľvek, čo umožňuje jednotlivým častiam softvéru komunikovať medzi sebou. Ide o súhrn funkcií a procedúr, tried, komunikačných protokolov a ďalších nástrojov.

Ide o to, aby metódy pre komunikáciu boli presne definované. Programátor, ktorý vytvára nový komponent systému, potom vie (alebo môže nájsť v dokumentácii), aké postupy môže použiť, aby jeho komponent správne fungoval v rámci ostatných komponentov.

Ak si chcete API predstaviť ako niečo z bežného života, tak si predstavte čašníka v reštaurácii, ktorý zaisťuje (a prekladá) komunikáciu medzi hosťom a kuchárom. Alebo ako palubnú dosku automobilu, ktorá pomocou presne definovaných metód (tlačidla na doske) odovzdá to, čo vodič (jeden komponent) chce inému komponentu (motoru). A návod k autu je ako API dokumentácia, kde sú jednotlivé metódy (tlačidlá) popísané.

Existujú grafické API, API pre frameworky a knižnice, API operačných systémov. Nás budú zaujímať hlavne webová API.

Webová API

Webové API definuje, ako spolu komunikujú nejaké komponenty po internete. Typicky sa jedná o dve časti aplikácie:

webová stránka si doťahuje zo servera potrebné dáta pomocou AJAX dotazu alebo
mobilné aplikácie si sťahuje dáta z webu).

Synonymom môže byť webová služba. Naše webové API, ktoré si v kurze nakoniec vytvoríme, bude umožňovať vykonávať operácie nad databázou filmov, napr. vyhľadá existujúci film alebo vloží nový film. Webové API samozrejme nie sú obmedzené len na databázy, môžeme cez ne posielať SMS, zistiť aktuálne počasie a podobne.

Ukážka webového API

Malinké, ale veľmi populárne API medzi slovenskými e-shopmi, beží na stránkach Českej národnej banky, konkrétne na adrese: https://www.cnb.cz/…nni_kurz.txt

Keď si adresu otvoríme, vypíše sa nám kurz mien pre aktuálny deň. Všimnime si, že sa nevygenerovala žiadna HTML stránka, ale surové dáta vo formáte CSV. Webové API totiž nie sú určené pre ľudí, ale pre programy. Výstup API vyzerá takto:

https://www.cnb.cz/cs/financni_trhy/devizovy_trh/kurzy_devizoveho_trhu/denni_kurz.txt

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

Jednoduché API sme si už predstavili na ukážke s kurzami ČNB. 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 jednoduché API sa môže používať aj formát XML alebo JSON.

Jednoduchá API typicky ponúka len nejaký zoznam dát na stiahnutie, napr. počasie podľa mesta, a 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 (značkovací jazyk podobný HTML). SOAP je orientovaný na procedúry. To sa prejavuje aj v spôsobe volania. URL bude typicky obsahovať nejaké sloveso. 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 by bez dlhej hlavičky, ktorú som vypustil, vyzerala napr. 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é 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.

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 je orientovaný na dáta. URL bude obsahovať typicky nejaké podstatné meno (v našom prípade to bude treba podstatné meno movies, ako uvidíme neskôr). 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 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.

Pre našu aplikáciu použijeme práve RESTful API, a to z dôvodov jednoduchosti a stručnosti. Ďalším dôvodom je potreba nad filmami vykonávať operácie, pre ktoré je RESTful API navrhnuté.

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

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 pre 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ľ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.

HTTP

Nakoniec si ešte povieme niečo málo o vyššie spomínanom HTTP. Hyper Text Transfer Protocol, skrátene HTTP, je jedným z najrozšírenejších protokolov používaných na komunikáciu po internete. Protokol môžeme chápať ako súhrn pravidiel, ktoré by mal nejaký systém dodržiavať pri komunikácii s iným systémom.

Komunikácia pomocou tohto protokolu je založená na otázkach (požiadavkách) a odpovediach na ne. Klient posiela otázky na webový server a ten mu naspäť zasiela odpovede s dátami. Klientom môže byť napríklad webový prehliadač, ktorý žiada webový server o zaslanie HTML stránky:

Schéma zaslania požiadavky na stránku - ASP.NET Core Web API

Tento protokol nevie uchovávať súvislosť medzi otázkami, jedná sa preto o tzv. stateless (bezstavový) protokol. Server vníma všetky otázky ako na sebe nezávislé a uchovanie stavu, napr. identity užívateľa, si musí riešiť samotný klient. Dnes je už štandardom zabezpečená verzia tohto protokolu, označovaná HTTPS.

Štruktúra HTTP otázky a odpovede

Otázky klienta musia predovšetkým obsahovať:

Typ dotazu, teda tzv. HTTP metódu - pár základných HTTP metód sme si zmienili už vyššie, konkrétne GET, POST, PUT a DELETE
Adresu dotazu nesúcu informáciu o tom, aké dáta a odkiaľ sú žiadané.

Ďalej môže mať otázku ešte aj tzv. hlavičky obsahujúce dodatočné informácie, napr.

o klientovi,
a prípadne aj tzv. telo s dátami, ktoré chceme poslať s otázkou na server.

Odpoveď servera sa potom skladá najmä zo:

stavu požiadavky, teda jeho úspešnosti,
hlavičiek obsahujúcich dodatočné informácie o prenášaných dátach, napr. o type dát,
samotných dát.

Prenášanými dátami v odpovedi môže byť akýkoľvek textový dokument. Väčšinou sa jedná o dokumenty vo formáte HTML, XML, JSON alebo napríklad CSV.

To by bolo pre teoretický úvod všetko.

Nabudúce, v lekcii ASP.NET Web API - Sprevádzkovanie projektu , si založíme projekt vo Visual Studio a sprevádzkováme javascriptového klienta, ktorý bude užívateľovi sprostredkovávať dáta z nášho webového API.

Článok pre vás napísal Radek Vymětalík

Užívateľské hodnotenie:

2 hlasov

...

Aktivity