Lekce 1 - ASP.NET Web API - Úvod

Vítejte v kurzu o tvorbě webového API filmové databáze pomocí technologie ASP.NET Core v jazyce C# .NET.

Tento kurz navazuje na kurz Základy ASP.NET Core MVC, kde jsme tvořili aplikace kompletně jen pomocí technologie ASP.NET Core MVC, HTML a CSS. V minulosti se všechny aplikace tímto způsobem opravdu tvořily, dnes je však již vytlačuje způsob nový.

Aplikace s API serverem a klientem v JavaScriptu

V praxi se totiž na webu používá spoustu aplikací, které jsou opravdu spíše aplikacemi, než webovými stránkami s články. Vezměme si například takové Spotify nebo Google Dokumenty. Od takových aplikací uživatel čeká spíše chování jako mají desktopové aplikace, u kterých nemusí čekat na přenačtení celé stránky po kliknutí na tlačítko, jako je tomu u tradičních webových aplikací. Proto se dnes většina aplikací již takto neprogramuje.

To však neznamená, že by webové aplikace založené na MVC architektuře neměly na trhu své místo a nevyplatí se je tedy ani učit vytvářet. Tato technologie se například hodí na weby zaměřené na články (ITnetwork takto funguje) nebo na e-shopy.

Moderní aplikace jsou rozdělené na dvě části:

• webový server s databází a API,
• mohutný klient v JavaScriptu.

V tomto kurzu se zaměříme na tu první část, tedy tvorbu webového API, a klienta si vypůjčíme ze zdejších kurzů na technologie React nebo Angular.

V obou kurzech se programuje klient pro správu databáze filmů. Našim úkolem bude vytvořit tuto databázi spolu s webovým API zprostředková­vajícím komunikaci s daným klientem. Nakonec budeme schopni data o filmech přidávat, upravovat nebo mazat a samozřejmě si je i prohlížet:

Požadavky na znalosti

Tento projekt je na pomezí junior/medior, co se týče levelu znalostí. V rámci levelu junior se předpokládá především orientace v tomto C# .NET projektu. Může se tedy stát, že vždy nebudeš úplně všemu rozumět. Pokud bys chtěl detailně pochopit veškerý kód a používané principy, pomohou ti znalosti v rozsahu levelu medior.

Junior-level znalosti

Konkrétněji se v rámci levelu junior předpokládají znalosti v tomto rozsahu:

• Základní konstrukce jazyka C# .NET
• Objektově orientované programování v C# .NET
• Kolekce Seznam, Slovníky a LINQ v C# .NET
• Základy ASP.NET Core MVC
• Visual Studio

Medior-level znalosti

Pokud bys chtěl detailně pochopit veškerý kód, pomohou ještě následující znalosti, nicméně počítej s vyšší časovou náročností:

• Základy React nebo Základy Angular
• Databáze v C# - ADO.NET
• Dependency injection a softwarové architektury
• Debugging.

Nyní si již řekneme, co to API vlastně je a jaké máme jeho druhy.

API

API je zkratka pro Application Programming Interface, česky aplikační programové rozhraní. Je to obecně cokoli, co umožňuje jednotlivým částem softwaru komunikovat mezi sebou. Jedná se o souhrn funkcí a procedur, tříd, komunikačních protokolů a dalších nástrojů.

Jde o to, aby metody pro komunikaci byly přesně definované. Programátor, který vytváří novou komponentu systému, potom ví (nebo může najít v dokumentaci), jaké postupy může použít, aby jeho komponenta správně fungovala v rámci ostatních komponent.

Pokud si chceme API představit jako něco z běžného života, tak si můžeme představit číšníka v restauraci, který zajišťuje (a překládá) komunikaci mezi hostem a kuchařem. Nebo jako palubní desku automobilu, která pomocí přesně definovaných metod (tlačítka na desce) předá to, co řidič (jedna komponenta) chce jiné komponentě (motoru). A návod k autu je jako API dokumentace, kde jsou jednotlivé metody (tlačítka) popsané.

Existují grafická API, API pro frameworky a knihovny, API operačních systémů. Nás budou zajímat hlavně webová API.

Webová API

Webové API definuje, jak spolu komunikují nějaké komponenty po internetu. Typicky se jedná o dvě části aplikace, příkladem mohou být tyto dvě situace:

• webová stránka si dotahuje ze serveru potřebná data pomocí AJAX dotazu,
• mobilní aplikace si stahuje data ze serveru.

Jak webová stránka, tak mobilní aplikace musí se serverem komunikovat přes nějaké webové API. Synonymem může být webová služba.

Naše webové API, které si v kurzu nakonec vytvoříme, bude umožňovat provádět operace nad databází filmů, např. vyhledá existující film nebo vloží film nový. Webová API samozřejmě nejsou omezená jen na databáze, můžeme přes ně posílat SMS, zjistit aktuální počasí a podobně.

Ukázka webového API

Malinké, ale velmi populární API mezi českými e-shopy, běží na stránkách České národní banky, konkrétně na adrese: https://www.cnb.cz/…nni_kurz.txt

Když si adresu otevřeme, vypíše se nám kurz měn pro aktuální den. Všimněme si, že se nevygenerovala žádná HTML stránka, ale surová data ve formátu CSV. Webová API totiž nejsou určená pro lidi, ale pro programy. Výstup API vypadá takto:

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.

Protokol můžeme chápat jako souhrn pravidel, která by měl nějaký systém dodržovat při komunikaci s jiným systémem.

Jednoduchá API

Jednoduché API jsme si již představili na ukázce s kurzy ČNB. Položky jsou na jednotlivých řádcích a hodnoty jsou oddělené nějakým speciálním znakem (v CSV s měnami kurzu to jsou svislítka). Na jednoduchá API se může používat i formát XML nebo JSON.

Jednoduchá API typicky nabízí jen nějaký seznam dat ke stažení, např. počasí podle města, a 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 (značkovací jazyk podobný HTML). SOAP je orientovaný na procedury. To se projevuje i ve způsobu volání. URL bude typicky obsahovat nějaké sloveso. 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 by bez dlouhé hlavičky, kterou jsem vypustil, vypadal např. 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á a to i 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.

REST

REST je v současné době velmi oblíbená architektura rozhraní. Je to zkratka 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 je orientovaný na data. URL bude obsahovat typicky nějaké podstatné jméno (v našem případě to bude třeba podstatné jméno movies, jak uvidíme později). REST implementuje čtyři základní CRUD operace. Tyto operace jsou vytvořit (Create), číst (Read), změnit (Update) a smazat (Delete). V HTTP 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í a na používání. Oproti SOAP je mnohem stručnější a tedy efektivnější. I přes svoji stručnost obsahuje každý požadavek 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.

Pro naši aplikaci použijeme právě RESTful API, a to především z důvodů jednoduchosti a stručnosti. Dalším důvodem je potřeba nad filmy provádět operace, pro které je REST architektura navržená.

API založené na REST architektuře se označuje jako RESTful.

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 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, email 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 je třeba si při každém dotazu říci, co přesně nás zajímá.

HTTP

Nakonec si ještě řekneme něco málo o výše zmiňovaném HTTP. Hyper Text Transfer Protocol, zkráceně HTTP, je jedním z nejrozšířenějších protokolů používaných ke komunikaci po internetu.

Komunikace pomocí tohoto protokolu je založená na dotazech (požadavcích) a odpovědích na ně. Klient posílá dotazy na webový server a ten mu nazpět zasílá odpovědi s daty. Klientem může být například webový prohlížeč, který žádá webový server o zaslání HTML stránky:

Tento protokol neumí uchovávat souvislost mezi dotazy, jedná se proto o tzv. stateless (bezstavový) protokol. Server vnímá všechny dotazy jako na sobě nezávislé a uchování stavu, např. identity uživatele, si musí řešit samotný klient.

Dnes je již standardem zabezpečená verze tohoto protokolu, označována HTTPS.

Struktura HTTP dotazu a odpovědi

Dotazy klienta musí především obsahovat:

• typ dotazu, tedy tzv. HTTP metodu - pár základních HTTP metod jsme si zmínili již výše, konkrétně GET, POST, PUT a DELETE,
• adresu dotazu nesoucí informaci o tom, jaká data a odkud jsou žádána.

Dále dotaz ještě může (ale nemusí) mít i:

• hlavičky obsahující dodatečné informace, např. o klientovi,
• tělo s daty, která chceme poslat s dotazem na server.

Odpověď serveru se pak skládá zejména ze:

• stavu požadavku, tedy jeho úspěšnosti,
• hlaviček obsahujících dodatečné informace o přenášených datech, např. o typu dat,
• samotných dat.

Přenášenými daty v odpovědi může být jakýkoliv textový dokument. Většinou se jedná o dokumenty ve formátu HTML, XML, JSON nebo třeba CSV.

To by bylo pro teoretický úvod vše.

Příště, v lekci ASP.NET Web API - Zprovoznění projektu, si založíme projekt ve Visual Studio a zprovozníme javascriptového klienta, který bude uživateli zprostředkovávat data z našeho webového API.

 

Měl jsi s čímkoli problém? Zdrojový kód vzorové aplikace je ke stažení každých pár lekcí. Zatím pokračuj dál, a pak si svou aplikaci porovnej se vzorem a snadno oprav.