Dzisiaj ostatnia warstwa modelu, która zdecydowanie często jest pomijana w implementacjach REST. Moim zdaniem, w przypadku publicznych API jest bardzo ważna, szczególnie w środowisku mikro-serwisów, gdzie nawigacja jest utrudniona ze względu na liczbę usług.

HATEOAS to skrót od Hypertext As The Engine Of Application State. Mechanizm dostarcza możliwość nawigacji przez zasoby bez wiedzy o konkretnych adresach URL.  Załóżmy, że mamy bazę klientów w systemie i możemy w niej:

1. Wylistować listę klientów.
2. Zwrócić dane konkretnego klienta.
3. Aktualizować dane.
4. Usuwać klienta z bazy.
5. Zwracać poszczególne dane takie jak dane kontaktowe, adres itp.

Projektując serwis zgodnie z poprzednimi zasadami, otrzymalibyśmy następujące linki:

1. GET /customers
2. GET /customers/{id}
3. PUT /customers i w ciele dane klienta
4. DELETE /customers/{id}
5. GET customers/{id}/email, customers/{id}/address itd.

Bez warstwy trzeciej, klient musi znać te linki. Innymi słowy, klient musi znać implementację wewnętrzną serwera i w przypadku jakiejkolwiek zmiany, wszyscy klienci muszą zaktualizować kod. Klient tak naprawdę powinien tylko wiedzieć co chce zrobić, a nie jak to ma zrobić.

W przypadku hateoas, konsument musi znać dane tylko korzenia. Załóżmy, że wykonujemy zapytanie HTTP GET /customers, aby wylistować wszystkie osoby w bazie. Jako odpowiedz przyjdzie coś w rodzaju:

HTTP/1.1 200 OK

<Customers>
  <Customer FirstName="Piotr" Last="Zielinski" Id="1">
     <link rel = "details" uri = "/customers/1"/>
     <link rel = "address" uri = "/customers/1/address"/>
  </Customer>
  <Customer FirstName="afaf" Last="sfsagsa" Id="2">
     <link rel = "details" uri = "/customers/2"/>
     <link rel = "address" uri = "/customers/1/address"/>
  </Customer>
</Customers>

Analogicznie, dodając nową osobę do bazy czyli HTTP POST /customers/, dostaniemy w odpowiedzi również mapę linków:

HTTP/1.1 201 Created


<Customer FirstName="Piotr" Last="Zielinski" Id="1">
     <link rel = "details" uri = "/customers/1"/>
    <link rel = "address" uri = "/customers/address"/>
</Customer>

Jak widzimy, to serwer decyduje, co klient może zrobić. Odpowiedź określa również aktualny stan aplikacji, czyli co możemy ze zwróconymi zasobami, w danym momencie zrobić.  API zaprojektowane w ten sposób ma zatem wbudowany mechanizm discovery – przekazujemy konsumentowi tylko korzeń, a on sam już jest w stanie przeglądać i wykonywać dowolne operacje na zasobach.

W dwóch postach poruszałem już temat dokumentacji usług REST. Ręczne tworzenie plików JSON dla swagger jest dosyć czasochłonne i łatwo potem zapomnieć przy jakiś modyfikacjach o aktualizacji dokumentacji.

Dla ASP.NET MVC WebAPI na szczęście jest Swashbuckle. Zacznijmy od instalacji odpowiedniego pakietu:

Install-Package Swashbuckle

Zobaczymy, że został dodany m.in. plik SwaggerConfig.cs. Wpisując teraz adres /swagger np. “http://localhost:35447/swagger” ujrzymy automatycznie wygenerowaną dokumentację:

Polecam również włączenie komentarzy XML, jak to było w przypadku ASP.NET HelpPages. Przechodzimy do właściwości projektu i zaznaczamy XML Documentation File:

Następnie możemy odkomentować następującą linię:

c.IncludeXmlComments(GetXmlCommentsPath());

Gdzie GetXmlCommentsPath to:

private static string GetXmlCommentsPath()
{
    return System.String.Format(@"{0}\App_Data\XmlDocument.xml", System.AppDomain.CurrentDomain.BaseDirectory);
}

Teraz w komentarzach możemy określić parametry, zwracane kody itp.:

public class SampleController : ApiController
{
    /// <summary>
    /// Any method description
    /// </summary>
    /// <param name="id">Id of something</param>
    /// <remarks>Any remarks</remarks>
    /// <response code="400">Bad request</response>
    /// <response code="500">Internal Server Error</response>
    public int Test(int id)
    {
        return 0;
    }
}

Przechodząc do Swagger, zobaczymy:

Martin Fowler, kilka lat temu pisał o tzw. Richardson maturity model, którego autorem jest tak naprawdę Leonard Richardson. Groźnie brzmiąca nazwa, jak zwykle nie opisuje nic bardzo skomplikowanego. Nie mniej jednak, model ten doskonale opisuje założenia usług RESTful. W zasadzie nie ma framework’ów, które wymuszałyby poprawną implementację REST, stąd niezbędne jest zrozumienie jakie są założenia tych usług. Programiści zbyt często luźno interpretują pojęcie REST. Moim zdaniem, w momencie, gdy REST wchodził, nie było jasnej definicji wymagań i założeń.

Model jest podzielony na cztery poziomy (Level 0, Level 1, Level 2, Level 3). Jeśli zaimplementujemy wszystkie z nich, wtedy możemy mówić, że w pełni implementujemy model. Nie znaczy to jednak, że nasza usługa będzie automatycznie REST, ponieważ jest to dużo bardziej złożone niż przedstawiany tutaj model. Moim zdaniem są to po prostu fundamenty usługi. Nie znaczy to również, że bez poziomu trzeciego, nasza usługa jest zła – wszystko zależy od wymagań.

Poziom 0

Zacznijmy od zerowego poziomu. Mówi on po prostu to, że usługa REST to nie nowy protokół, a całość komunikacji jest już oparta na istniejącym protokole. Najczęściej jest to po prostu tunelowanie HTTP, czyli wykorzystanie HTTP z odpowiednim nagłówkiem i ciałem. Przykładowo, aby dodać nowego klienta do bazy, możemy wysłać:

POST /customerService HTTP/1.1

<AddCustomer FirstName="Piotr" LastName="Zielinski"/>

Jako odpowiedź dostaniemy wtedy HTTP 200. Na poziomie zerowym, będzie zawsze to 200. W przypadku niepowodzenia operacji, po prostu błąd będzie dołączony jako opis (np. w formancie  XML), ale status zawsze będzie 200.

Jeśli chcemy zwrócić informacje o konkretnym kliencie, również wysyłamy zapytanie za pomocą HTTP:

POST /customerService HTTP/1.1

<GetCustomer id=1/>

Odpowiedź:

HTTP/1.1 200 OK

<Customer FirstName="Piotr" LastName="Zielinski"/>

Jak widzimy, HTTP służy nam do komunikacji. W ciele wstawiamy nasze zapytanie. Nie jest to nic innego jak RPC, czyli zdalne wywoływanie procedur. Można to porównać do klasycznych usług, gdzie wywołujemy po prostu konkretne metody na danej usłudze.

Poziom 1

Poziom pierwszy wprowadza definicje zasobów. Nie będziemy już wysyłać zapytań do jednego punktu, ale usługa będzie tworzyć hierarchie zasobów. Innymi słowy, aby zwrócić dane klienta, wystarczy:

POST /customerServices/customers/1 HTTP/1.1
<GetCustomer/>

Proszę zwrócić uwagę na adres. Dane uzyskujemy wysyłając zapytanie do konkretnego adresu, a nie głównego, jak to było  w warstwie zerowej. Innymi słowy, aby np. zwrócić numer telefonu klienta o identyfikatorze 1, wysyłamy:

POST /customerServices/customers/1/phone HTTP/1.1
<GetPhoneNumber/>

W przypadku poziomu zerowego, byłoby to:

POST /customerServices HTTP/1.1
<GetCustomerPhone id="1"/>

Kluczami do zrozumienia poziomu 1, są słowa “hierarchia” oraz “zasoby”. Nie odwołujemy się do głównego adresu, ale konkretne zapytania tworzą po prostu drzewo zasobów.

Poziom 2

Proszę zauważyć, że wszystkie powyższe zapytania korzystały wyłącznie z HTTP Post. Poziom drugi rozpoznaje typ zapytania, tzn. POST, PUT, GET, DELETE. W celu zwrócenia danych konkretnego klienta wystarczy:

GET /customerServices/customers/1 HTTP/1.1

GET służy zatem do zwracania danych i nie trzeba już tego określać w HTTP body za pomocą nazwy komendy, jak to było w poprzednich warstwach. HTTP PUT zwykle służy do aktualizacji danych, POST do wstawiania nowych wierszy, a DELETE naturalnie do ich usuwania.

Ponadto jest różnica w jaki sposób zwracamy odpowiedź. W poprzednich warstwach było to po prostu HTTP 200 OK plus ewentualnie jakiś opis. Teraz chcemy dostarczyć bardziej dokładną odpowiedź. Na przykład, po dodaniu klienta dostaniemy:

HTTP/1.1 201 Created
Location: /customers/1

Jak widać, operujemy tutaj na statusie HTTP i nie zwracamy tylko 200, a np. 201, gdy nowy zasób został dodany. Ponadto dobrze zwrócić również lokalizacje właśnie dodanego zasobu (Location). Zamiast zwracania treści błędu, jak to miało miejsce na poziomach 01,2, zwracamy konkretny status HTTP, który ma już dobrze znaną definicję ze standardów webowych.

Do opisania pozostał jeszcze poziom 3, ale tym zajmiemy się w kolejnym poście bo jest on nieco bardziej skomplikowany.

Z dzisiejszego postu powinno jasno wynikać, że usługi REST to kompletnie inna idea niż usługi SOAP i klasyczny RPC. Tutaj nie chodzi po prostu o wywołanie jakieś metody na usłudze.

Podsumowując:

1. Poziom  0 – REST powinien być oparty na istniejącym protokole np. HTTP.

2. Poziom 1 – Zasoby oraz ich hierarchia.

3. Poziom 2 – HTTP verbs oraz HTTP status codes.

Największa zaleta mikro-serwisów, a mianowicie pojedyncza odpowiedzialność, często bywa również problemem, a raczej wyzwaniem. Załóżmy, że nasz system ma następujący mikro-usługi:

1. CustomerService – podstawowe informacje o klientach
2. AddressService – wyszukiwarka adresów
3. CreditCardDetails – dane o kartach

Nie chce wymieniać tutaj długiej listy, ale wyobraźmy sobie, że mamy 10 usług co jest normą w przypadku mikro-serwisów. Często w celu wykonania jednej operacji (np. dokonanie płatności w sklepie internetowym), musimy zgromadzić informacje z różnych usług – np. w celu wystawienia faktury.

Oznacza to, że nasz klient będzie musiał łączyć się z wszystkimi nimi, w celu uzyskania danych. Rozwiązanie jest nie tylko wolne (liczba połączeń), ale i brzydkie – klient musi znać wewnętrzna architekturę naszych usług. Często kod po stronie klienta może przypominać spaghetti ze względu, że odwołuje się do tylu różnych usług

Innymi słowy, rozdrobnienie usług, a sposób w jaki klient je konsumuje zwykle jest różny. Dane o kliencie (ConsumerService) oraz o adresach zamieszkania (AddressService) zwykle konsumowane są jednocześnie i z punktu widzenia klienta, jest to nienaturalne, że pochodzą z dwóch różnych usług.

Z tego względu, warto rozważyć wzorzec gateway, który jest po prostu punktem centralnym i dostępowym do naszych mikro usług, o których klient nie powinien często nawet wiedzieć. Idea mikro-serwisów polega na możliwości ich wprowadzenia w każdym momencie, bez wielkich zmian po stronie klienta.

Jak widać z rysunku, implementacja gateway może sprowadzać się do zwykłego proxy. Klient wysyła zapytanie tylko do jednego punktu, a potem jest to już odpowiedzialność bramki, aby odpowiednio komunikować się z mikro-usługami.

Oczywiście nie możemy mieć logiki biznesowej w bramce. Jedynie co gateway zawiera to proxy, caching, autoryzacja i inne “cross-cutting concerns”, czyli problemy niezależne od usługi.

Gdybyśmy jakąś logikę wrzucili do gateway, to skończylibyśmy na starym monolitycznym SOA.

W następnych wpisach zajmiemy się implementacją bramki ponieważ nie jest to takie oczywiste. Często, szczególnie w przypadku REST, mamy do dyspozycji z różnymi typami klientów. Na przykład, aplikacja mobilna może nie potrzebować wszystkich danych na raz. Z tego względu, bramka powinna być zaimplementowana w sposób generyczny, eksponując różne API, w zależności od kontekstu.

Kolejnym zagadnieniem, którym  musimy się zając jest agregacja danych, nierzadko z różnych usług. Jeśli mamy 10 usług, to klient może zażądać dowolnej kombinacji (np. CustomerService,CreditCardDetails lub CreditCardsService, AddressService).

Wynika z tego, że będziemy musieli opracować elastyczne rozwiązanie bo oczywiście nie jesteśmy w stanie zaimplementować sami wszystkim metod, biorąc pod uwagę, że w każdej chwili infrastruktura mikro-usług może zmienić się.

Dzięki takiemu rozwiązaniu, zachowamy łatwość w utrzymaniu i wdrażaniu usług, a jednocześnie nie będziemy mieli spaghetti po stronie klienta.