Abstrakt:

  1. Czym jest REST API?
  2. Krótko o protokole HTTP.
  3. Narzędnia do testowania API (subiektywny wybór najlepszych narzędzi według autora)
    • Postman
    • Newman i NPM
    • RestAssured
    • Visual Studio Code + REST Client
    • RestSharp


Czym jest REST API?

To pytanie często pojawia się na rozmowach kwalifikacyjnych. Aby wyjaśnić to złożone pojęcie, najpierw wyjaśnię je oddzielnie.

Representation State Transfer jest architekturą i podejściem do komunikacji opisanymi przez Roya Fieldinga.

API natomiast to Application Programming Interface, czyli interfejs (ścisły zestaw reguł) po którym komunikujemy się pomiędzy aplikacjami w celu wymiany informacji.

REST API to połączenie API z architekturą REST.

Jakie więc jest to podejście konkretnie? Możemy opisać je w kilku punktach.

  1. Architektura klient – serwer
    • Klient jest całkowicie odseparowany od serwera.
  2. Bezstanowość
    • Architektura REST nie przetrzymuje informacji pomiędzy zapytaniami a serwer nie zapamiętuje żadnych informacji o kliencie.
  3. Warstwowość
    • Klient nie wie czy jest podłączony do serwera czy do pośrednika, jeżeli mamy 5 warstw – to każda warstwa jest świadoma tylko warstwy z którą komunikuje się bezpośrednio (i nie wie o istnieniu innych warstw).
  4. Cacheable (keszowalność?)
    • Klient przetrzymuje zasoby po swojej stronie (np. nie ma potrzeby ściągania przy każdym zapytaniu tego samego obrazu .jpg, więc klient zapisuje go na dysku i dopóki suma kontrolna pliku pozostaje niezmienna nie pobiera go ponownie)
  5. Jednolity interfejs
    • dla wszystkich zasobów, serwer utrzymuje ten sam interfejs (na przykład serwer wysyła dane do klienta w formacie JSON lub XML niezależnie od wewnętrznej reprezentacji danych serwera)
    • każdy zasób ma swoje unikalne URI (np. http://scvconsultants.com/users zwróci listę użytkowników, a http://scvconsultants.com/user/1 zwróci użytkownika numer 1)
    • samoopisujące się wiadomości – każda wiadomość zawiera tyle informacji ile jest potrzebne do opisania jak ją przetworzyć
    • HATEOAS czyli Hypermedia As The Engine of Application State – można powiedzieć, że to trzeci poziom REST API, który spełnia wszystkie założenia opisane w tym poście

Krótko o protokole HTTP.

Pełna definicja protokołu HTTP znajduje się tutaj (co polecam czytać kawałkami w trakcie przygotowania do testowania REST API).

REST API wykorzystuje głównie 5 zapytań z protokołu HTTP. Poniżej przykłady zapytań i prawidłowych odpowiedzi na nie.

HTTP requestCRUDPełna kolekcja (np. /users)Pojedyńczy element (np. /user/{id})
POSTCreate201 (Created), 'Location' header z linkiem do /customers/{id} zawierającym nowe ID.404 (Not Found), 409 (Conflict) jeżeli zasób już istnieje
GETRead200 (OK), zwraca listę wszystkich użytkowników. Użyj paginacji, sortowania i filtrowania do nawigacji po dużych listach.200 (OK), pojedyńczy user. 404 (Not Found), jeżeli ID nie zostało znalezione lub jest nieprawidłowe
PUTUpdate/Replace405 (Method Not Allowed), o ile nie chcesz zaktualizować WSZYSTKICH zasobów w kolekcji.200 (OK) or 204 (No Content). 404 (Not Found), jeżeli ID nie zostało znalezione lub jest nieprawidłowe
PATCHUpdate/Modify405 (Method Not Allowed), jak wyżej200 (OK) or 204 (No Content). 404 (Not Found), jeżeli ID nie zostało znalezione lub jest nieprawidłowe
DELETEDelete405 (Method Not Allowed), o ile nie chcesz usunąć wszystkich danych z poziomu REST API.200 (OK). 404 (Not Found), jeżeli ID nie zostało znalezione lub jest nieprawidłowe

 


Narzędzia do testowania API

Postman

Narzędzie (samodzielna aplikacja, która historycznie wyewoluowała z addona do przeglądarki Chrome) z ładnym i intuicyjnym GUI do testowania zapytań.

Dlaczego warto z niego korzystać:

  • Jest darmowy (wersja płatna ma kilka usprawnień, ale do zwykłego testowania wystarczy nam bezpłatna)
  • Szybki i intuicyjny próg wejścia (zapytania tworzymy w intuicyjnych okienkach i wciskamy „Send”)
  • Możliwość pisania testów w JavaScript do każdego zapytania
  • Możliwość tworzenia kolekcji (łańcuchów wielu zapytań) z których każde ma swoje testy i potrafią przekazywać dane między sobą
  • Możliwość mockowania odpowiedzi z API
  • Obsługa wielu środowisk
  • Wbudowany runner testów i automatyczne raportowanie
  • Istnieją wersje dla wszystkich popularnych systemów operacyjnych.
  • Wspiera import dokumentacji Swaggera, która sama tworzy odpowiednie zapytania do API. Wystarczy użyć funkcji Import From Link jak na screenie poniżej

Minusy stosowania Postmana:

  • Mała elastyczność (brak możliwości wysyłania zapytania GET z body ;))
  • Konieczność pisania testów w JavaScript (brak obsługi innych języków)
  • Brak podpowiedzi składni w edytorze testów.
  • Płatne, dość kosztowne funkcje jeżeli chcemy pracować w zespole rozproszonym

 

Newman + NPM

Narzędzie CLI do uruchamiania testów i zapytań stworzonych w Postmanie. Wymaga NPMa, który pozwoli uruchomić testy api w konsoli na dowolnym systemie operacyjnym (i generować jakże potrzebne naszym menadżerom kolorowe (zielonoczerwone) raporty).

.

RestAssured

Biblioteka w Javie do pisania testów REST API. Jeżeli projekt pisany jest w Javie i nasze środowisko CI jest już skonfigurowane – może być dobrym pomysłem wykorzystać Javę do automatyzacji testów (unikniemy narzutu instalacji NPMa, dodatkowej konfiguracji Jenkinsa, TeamCity czy VSTS).

Dlaczego wybrałem akurat tą?

  • Wsparcie community
  • Open source
  • Nieduży próg wejścia
  • Bardzo dobrą dokumentacja.
  • Testy pisane w stylu Gherkina (Given / When / Then) i duża czytelność kodu

Chętnym na zapoznanie się z tym polecam wpis na blogu Sławka z przykładami kodu w Javie: tutaj i tutaj

 

Visual Studio Code + REST Client

Addon do VS Code, do uruchamiania zapytań z poziomu IDE.

Wystarczy stworzyć plik .http, zapisać i możemy wysyłać jednym kliknięciem dowolne zapytania które tworzymy w pliku

Plusy:

  • Zerowy próg wejścia
  • Elastyczność (chcemy wysłać GET z body – proszę bardzo)
  • Darmowy addon do VS Studio, który zaczyna być najpopularniejszym edytorem kodu wśród programistów.

Minusy:

  • Trudno nazwać to testami automatycznymi, więc polecam to raczej do doraźnego stosowania w pojedyńczych przypadkach

 

RestSharp

Prosty klient REST API napisany w C#.

Plusy:

  • Open source
  • Wsparcie community
  • Prosta integracja ze SpecFlow i xUnit / nUnit
  • Dobra dokumentacja.

Minusy:

  • Jest to biblioteka do tworzenia REST Api a nie jego testowania, więc musimy sami sobie dopisać wiele rzeczy

Ponownie powtórzę jak mantrę: jeżeli nasz projekt pisany jest w języku X to nasze testy automatyczne powinny być pisane również w języku X. Chyba, że potrafimy uzasadnić koszty związane z różnymi językami naszym menadżerom.


Słowo i prośba na koniec

Jeżeli dotarłeś tutaj i chciałbyś się ze mną podzielić jakimś narzędziem, którego używałeś (i nie jest to SOAP UI, którego celowo pominąłem) to z miłą chęcią przeczytam Twój komentarz.