web api

rozwiązywanie problemu

Jednym ze sposobów na naukę programowania jest wykonywanie prostych aplikacji w określonej technologii od zera. Pozwala to na zapoznanie się z jej podstawowymi konceptami i przetestowanie ich w praktyce. Na przykład w przypadku aplikacji webowych można spróbować napisać pierwszą stronę internetową. Współcześnie jednak na witrynę składać się może wiele różnych aplikacji, które po połączeniu dają efekt widziany przez użytkownika. Część z tych programów to Web API odpowiedzialne za zwracanie danych, które przetwarzane są np. przez aplikacje frontendowe. W dzisiejszym artykule przyjrzymy się im bliżej.

Czym jest WebAPI?

Zacznijmy klasycznie od wyjaśnienia nazwy. API. To skrót od Application Programming Interface. W największym skrócie jest to aplikacja, która zajmuje się przetwarzaniem danych i zwracaniem ich w jednolitym formacie. Obecnie każda duża firma IT jak Google, Facebook, Twitter, etc. posiadają wiele swoich API.

aplikacje

Jak działa?

Podstawowy koncept, na którym są one zbudowane, to wysyłanie żądań i odbieranie odpowiedzi używając protokołu http, więcej o nich w tym artykule. Ciało response’a zawiera dane/zasób
o który pytaliśmy, wysyłając request. Najczęściej jest on serializowany do formatu JSON lub XML.
W dużym uproszczeniu działa to w następujący sposób:

– za pomocą protokołu http/https wysyłamy odpowiednie żądanie do API

– framework w jakim działa program obsługuje wiadomość http i zamienia ją na obiekt języka aplikacji

– request jest kierowany do odpowiedniego kontrolera i akcji

Kontroler to klasa zawierająca metody nazywane akcjami, obsługujące udostępnione przez programistów żądania, tzw. endpointy. Zdaję sobie sprawę, że może to brzmieć mgliście, dlatego najprościej będzie przedstawić Ci kod:


[Produces("application/json")]
[Route("api/Home")]
public class HomeController : Controller
{
    public ActionResult Index()
    {
        return Ok();
    }
}

infrastruktura

Implementacja w C#

Powyżej widzisz klasę kontrolera. Jak wspomniałem wyżej zawiera on akcje, które są wywoływane przez odpowiednie żądanie. Poprawny request musi zawierać adres URL, metodę http, protokół, nagłówki oraz opcjonalnie ciało. WebAPI działające we frameworku .NET implementuje to
w następujący sposób:

– każdy kontroler musi dziedziczyć po bazowej klasie Controller lub ControllerBase w zależności od wersji

– protokołem jest oczywiście http/https

– adres URL definiuje atrybut [Route]

– metoda http również opisywana jest za pomocą atrybutów, np.: [HttpPost], [HttpGet]

– nagłówki znajdują się w obiekcie Request.Headers dostępnym z poziomu akcji, a obsługiwanym
w klasie bazowej kontrolera

– ciało requestu (jeśli występuje) jest traktowane jako parametr wejściowy do akcji – używając atrybutu [FromBody] informujemy framework, aby wypełnił obiekt, który widnieje na liście parametrów, danymi przekazanymi w części body wysyłanego requestu. Jest to tzw. model binding.

Przekazywanie parametrów

Często zdarza się, że akcja przyjmuje jakieś parametry, może to być id jakiegoś elementu w bazie, inny prosty typ danych lub całe klasy, które będą obsługiwane przez API. Do przesyłania danych wykorzystuje się mechanizm parameter binding lub model binding i wyróżnia się 3 podstawowe sposoby:

  1. Pobieranie danych z ciała żądania – używając atrybutu [FromBody] informujemy framework, aby wypełnił obiekt, który widnieje na liście parametrów, danymi przekazanymi w body wysyłanego requestu
  2. Pobieranie danych z query – mechanizm przeznaczony do przekazywania typów prostych jak np. int lub bool. Parametry wejściowe akcji oznacza się atrybutem [FromQuery]. Przykładowy request może wyglądać następująco: http://host/kontroler/akcja?parametr=wartość
  3. Pobieranie danych z adresu URL – czasami taka ścieżka może być dobrym sposobem na przekazanie parametru. Robi się to według wzoru :

żądanie:

GET: http://host/kontroler/parametr/akcja

W składni C# definicja akcji powinna wyglądać następująco:


[Route("{parametr}/akcja")]
public ActionResult Index(string parametr) 
{ 
    return Ok(); 
}

Parametr ten jest przekazywany przez tzw. interpolację. W skrócie kod odszyfrowuje URL requestu widząc, że pomiędzy nazwą kontrolera, a akcją będzie występował parametr, którego wartością zostanie wypełniony parametr wejściowy metody o takiej samej nazwie. Jako typ parametru, oprócz stringa, możesz wybrać dowolny typ prosty.

W tym miejscu warto także wspomnieć o tym, że każde żądanie przed wywołaniem akcji kontrolera dodatkowo weryfikuje się pod kątem uprawnień. Domyślnie request może wysłany przez dowolnego klienta. Zachowanie to możemy oczywiście zmieniać, Służy do tego atrybut [Authorize] oraz definicja sposobu autoryzacji w klasie Startup w projekcie.

Całość opisanych mechanizmów składa się na tzw. endpoint, czyli sposób odpytania API o konkretny zasób.

Po odebraniu żądania, to przekazywane jest dalej, do klas je obsługujących. Ich implementacja zależeć będzie od wielu czynników, m.in. zadania jakie mają spełniać oraz architektury systemu, który rozwijamy. Jako, że każda aplikacja żądzi się swoimi prawami i założeniami, na potrzeby tego artykułu pominiemy tę część.

Zastosowanie Web API

aplikacja

Możesz zastanawiać się teraz do czego wykorzystuje się Web API. Najbardziej poprawną odpowiedzią będzie: do wszystkiego! Wyobraź sobie dowolną usługę internetową: płatności, sklepy, Facebook, YouTube, strony prezentujące obrazki i zdjęcia jak np. Pinterest i wiele, wiele innych. Każdą z nich można zbudować w oparciu o Web API, zarządzające całą logiką aplikacji. W takim przypadku, do udostępnienia danych użytkownikowi końcowemu będzie potrzebny dodatkowy program, który przedstawi je w graficznej formie lub wykorzysta do dalszej obróbki.
W tym miejscu jest pełna dowolność. Tym programem może być strona internetowa napisana
w javaScripcie, rozwiązanie mobilne – aplikacja na system iOS lub Android. Z Web API mogą także
z powodzeniem korzystać gry, aplikacje desktopowe, czy nawet mikrokontrolery, urządzenia przemysłowe i roboty. Jedynymi warunkami są dostęp do łącza internetowego oraz odpowiednie uprawnienia do odpytywania o zasoby. Jak więc widzisz zastosowań mogą być tysiące, a w efekcie na rynku widać ciągle rosnące zapotrzebowanie na specjalistów technologii backendowych, którzy będą pracowali nad rozwijaniem takich aplikacji.

Podsumowanie

W dzisiejszym artykule przybliżyłem Ci podstawowe koncepty i zastosowanie Web API. Doskonale zdaję sobie sprawę, że to co tutaj przedstawiłem, to zaledwie czubek góry lodowej, bo przy samej obsłudze requestu można wyróżnić około 40(!) kroków jakie są wykonywane za każdym razem, gdy go wysyłasz. Daj znać w komentarzu, czy temat jest dla Ciebie interesujący, i czy chciałbyś żebym go opisał. Mam nadzieję też, że po lekturze dzisiejszego wpisu jesteś bardziej zaciekawiony niż przerażony potencjałem jaki mają takie aplikacje. Podziel się swoimi opiniami
w komentarzu. Jeśli uważasz, że ten wpis może pomóc także innym, będę wdzięczny za każde udostępnienie w mediach społecznościowych, przyciski poniżej.

Please follow and like us:

Dodaj komentarz

This site uses Akismet to reduce spam. Learn how your comment data is processed.