Wprowadzenie

Na blogu pojawiło się już kilka wpisów poświęconych Postmanowi, który jest genialnym narzędziem do testowania Web API. Używam go praktycznie każdego dnia. Natomiast w dzisiejszym wpisie chciałbym Ci pokazać alternatywę (a tak naprawdę fajne uzupełnienie) Postmana. Jest nim dodatek REST Client do Visual Studio Code. Podobnie jak Postman, REST Client umożliwia wykonywanie żądań HTTP do serwera. A największą różnicą jest to, że zamiast graficznego interfejsu użytkownika mamy plik tekstowy, w którym znajdują się treści żądań.

Przykład do testów

Zanim przejdę do omawiania samego narzędzia, szybka informacja na temat Web API, które będziemy testować. W repozytorium (https://github.com/danielplawgo/RESTClientVSCode) przygotowanym do tego wpisu znajduje się bardzo proste REST API. Umożliwia ono wykonanie operacji (zwykły CRUD) na produktach, które znajdują się w bazie.

Pod spodem wykorzystany jest Entity Framework Core z bazą w pamięci z wygenerowanych kontrolerem dla klasy Product, co w tym przypadku ułatwia uruchomienie projektu i jest wystarczające do poznania funkcjonalności, jakie daje nam dodatek REST Client.

Testowa aplikacja standardowo jest uruchomiona pod adresem http://localhost:5000

REST Client

Aby skorzystać z tego narzędzia, należy mieć przede wszystkim Visual Studio Code. Później instalujemy dodatek https://marketplace.visualstudio.com/items?itemName=humao.rest-client

Jak wspomniałem we wstępie, dodatek REST Client wykorzystuje żądania zapisane w plikach tekstowych. Są to pliki o rozszerzeniu .http lub .rest. Proste żądanie GET po listę produktów wygląda tak:

Na początku określamy typ żądania (tutaj GET), adres (http://localhost:5000/api/Products – pod nim są dostępne dane w testowej aplikacji), a na końcu typ protokołu (HTTP/1.1). Jest tutaj wykorzystany standard RFC 2616 zapisu żądania.

Visual Studio Code wyświetla nad treścią żądania przycisk Send Request, który umożliwia jego wykonanie. Po wysłaniu go z prawej strony pojawia się nowe okno z treścią odpowiedzi:

Zmienne w REST Client

W REST Client podobnie jak to pokazywałem w Postmanie można wykorzystywać zmienne. Dzięki, którym możemy tworzyć bardziej uniwersalne żądania. W REST Client mamy kilka rodzajów zmiennych. Najbardziej podstawowe i przydatne to tak zwane zmienne plikowe (File Variables).

Zmienną plikową definiuje się z wykorzystaniem znaku @, po którym określa się nazwę zmiennej oraz jej wartość. Jak nazwa sugeruje, zmienna plikowa jest dostępna w całym pliku. Używamy jej w treści żądania lub definicji innych zmiennych poprzez otoczenie jej nazwy podwójnymi klamerkami. Tak jak to widać poniżej:

W pierwszej linijce zdefiniowałem zmienną baseUrl, zawierającą początek adresu, pod którym znajduje się testowana usługa. Natomiast w linijce trzeciej znajduje się definicja żądania, w którym użyłem zmiennej, używając zapisu {{baseUrl}}.

Ostateczny efekt jest taki sam jak w pierwszym przypadku: wykona się identyczne żądanie. Ale dzięki użyciu zmiennych możemy tworzyć łatwiejsze do zmiany żądania. Tak jak w tym przypadku wystarczy, że w jednym miejscu zmienię adres usługi i wszystkie żądania, które korzystają ze zmiennej będą wysyłały żądania pod nowy adres.

Zmienne możemy wykorzystywać w różnych miejscach definicji żądania. W adresie, jak to było wyżej, w treści, nagłówkach i tak dalej.

Żądanie jako zmienna

Drugim rodzajem zmiennych, które są bardzo przydatne, są tak zwane Request Variables. Dzięki nim możemy całe żądanie zapisać jako zmienną, a następnie z niego wyciągać różne przydatne informacje. Również z samej odpowiedzi z serwerach.

W kolejnym przykładzie będę chciał Ci pokazać, jak wykonać żądanie typu POST, które doda nowy produkt, a następnie zapisze do zmiennej plikowej productId id dodanego produktu. Dzięki temu w kolejnych żądaniach będziemy mogli wykorzystywać zapisane id i wykonywać kolejne operacje na dodanym produkcie. Do tego wykorzystamy właśnie zapisanie żądania jako zmienna:

Na początku zdefiniowałem zmienną plikową baseUrl. Od linijki numer 4 znajduje treść żądania typu POST, gdzie podobnie jak wcześniej określamy głównie typ żądania oraz adres. W kolejnej linijce (numer 5) określony jest nagłówek Content-Type. W tym miejscu możemy określić więcej nagłówków. Możemy też wykorzystać zdefiniowane zmienne.

Po nagłówkach i pustej linii znajduje się treść żądania (tutaj json), która zostanie wysłana do serwera (linijki 7 – 10). Tutaj określamy nazwę oraz opis produktu dla nowo dodawanego produktu. Oczywiście i tutaj w treści możemy używać zmiennych.

Natomiast w linijce numer 3 znajduje się właśnie zapisanie żądania jako zmienna. Linia zaczyna się od „# @name ” po czym następuje nazwa zmiennej (tutaj createProductRequest). Na pierwszy rzut oka może wydawać się to dziwne, ale łatwo można się do tego przyzwyczaić.

Użycie tak utworzonej zmiennej znajduje się w linijce 14. W niej tworzę nową zmienną o nazwie productId, w której będę przechowywał id utworzonego produktu. Tutaj właśnie korzystam ze zmiennej createProductRequest, z niej wyciągam na początku obiekt response (można też wyciągnąć obiekt request), a z niego obiekt body, w którym znajdować się będzie treść odpowiedzi. W tym przypadku odpowiedzią jest json, który zawiera pole id z identyfikatorem utworzonego produktu. Możemy też skorzystać z innych pól odpowiedzi, jak na przykład nagłówki. Po więcej szczegółów odsyłam do dokumentacji.

Wiele żądań

W tym przykładzie widać również jeszcze jedną ciekawą rzecz. W linijce 12 znajduje się potrójny znak #, który służy do separowania poszczególnych żądań w pliku, więc możemy mieć ich wiele w jednym pliku.

Poniżej znajdują się połączone powyższe żądania w jeden plik. Dodatkowo na końcu znajdują się dwa dodatkowe żądania (PUT oraz DELETE), aby mieć całego CRUDa produktów. W nich już nie ma nic szczególnego, więc nie opisuje ich dokładnie.

REST Client vs Postman

Dodatek REST Client ma dużo więcej funkcjonalności, niż pokazałem Ci w tym wpisie, na przykład jest więcej rodzajów zmiennych. Z czasem postaram się dodać kolejne wpisy na jego temat. Myślę jednak, że już teraz masz wystarczająco dużo informacji do efektywnej pracy.

Na końcu chciałem jeszcze porównać dodatek z Postmanem. A bardziej pokazać Ci, kiedy używam jednego i drugiego narzędzia. Jednym z większych minusów Postmana dla mnie są pliki z wyeksportowanymi żądaniami. Bardzo zależy mi na tym, aby były one przechowywane w repozytorium i aby każdy programista, czy tester w zespole mieli do nich dostęp. Oczywiście po zapłaceniu można to osiągnąć, ale również zależy mi nad śledzeniu zmian wraz ze zmianami w samym kodzie.

Tutaj właśnie pliki .http/.rest dużo lepiej się sprawdzają w stosunku do jsonów z Postmana. W takich plikach staram się zamykać jakieś scenariusze użycia fragmentu tworzonego API. Dzięki temu na przykład nowa osoba w zespole może w łatwy sposób przejść przez poszczególne żądania i w praktyce zapoznać się, jak skorzystać z danych akcji.

Postmana natomiast wykorzystuję w sytuacji, gdy potrzebuję zaimportować jakieś żądania z devtools, czy całe API z swagger – taka bieżąca praca. Na końcu natomiast te istotniejsze rzeczy przerzucam do plików .http/.rest, aby były w pewnym sensie dokumentacją API.

Przykład

Na githubie (https://github.com/danielplawgo/RESTClientVSCode) znajduje się przykład do tego wpisu. Do uruchomienie testowego Web API nie jest nic potrzebne, wystarczy je uruchomić i będzie dostępne ono pod adresem http://localhost:5000. W pliku requests.rest znajdują się przygotowane żądania, które można uruchomić z poziomu Visual Studio Code, po zainstalowaniu dodatku REST Client.

Podsumowanie

Dodatek REST Client do Visual Studio Code jest bardzo fajnym uzupełnieniem Postmana. Szczególnie gdy chcemy w repozytorium w łatwy i czytelny sposób przechowywać przykładowe żądania do tworzonego api, które mogą stanowić dokumentację użycia endpointów. A to bardzo się przydaje, gdy do projektu dołączają nowe osoby.