Co wykonujemy najczęściej podczas tworzenia aplikacji wystawiającej HTTP API? Chyba nie minę się z prawdą mówiąc, że requesty. Jakie są najpopularniejsze narzędzia do ich wysyłania? Większość z nas wskaże pewnie przeglądarkę, a zaraz potem cURL. Trudno się z tym nie zgodzić.
Ale co jeśli mam do czynienia z prawdziwym projektem?
Takim, który posiada dziesiątki różnych endpointów (jeśli nie jest zbyt duży). Gdzie każdy request typu GET może zawierać dużo różnych, interesujących nas kombinacji parametrów. Gdzie każdy POST może przesyłać skomplikowane struktury JSON. Gdzie praktycznie każdy request może, ale nie musi posiadać pewne nagłówki HTTP, od których zależy to, co zrobi nasza aplikacja (np. Authortization, Content-Type etc.). A do tego musimy jeszcze stworzyć i utrzymywać na bieżąco dokumentację do naszego API.
Nagle przeglądarka i cURL nie wyglądają już tak kolorowo. Na szczęście ludzie z Postdot Technologies postanowili nam to uprościć i to za całkowitą darmochę!
Co listonosz daje nam za darmo? (oprócz ulotek)
Zapewne każdy, kto maczał już palce w tworzeniu jakiegoś API natknął się w którymś momencie na aplikację o nazwie “Postman”. Można ją mieć w formie instalowanej w systemie lub jako wtyczkę do przeglądarki.
Na powyższym screenie widać, że możemy stworzyć sobie w bardzo łatwy sposób całą kolekcję interesujących nas requestów. Każdy z nich może mieć zapisane zestawy danych, parametrów, nagłówków, ciastek itp. Dodatkowo, odpowiedź możemy bardzo wygodnie przeglądać – możemy jednym kliknięciem skopiować całość do schowka, przeszukiwać zawartość oraz np. zwijać długie węzły w JSON’ach. To wszystko to niby nic wielkiego, ale nie sposób przecenić czasu jaki pozwala to sumarycznie zaoszczędzić podczas pracy nad wielomiesięcznym projektem.
Ponadto, bardzo łatwo możemy naszą kolekcję requestów przekazać komu chcemy. Na poniższym screenie jest pokazane okno “Share”, dostępne dla każdej naszej kolekcji, w której mamy dostępny unikalny link. Pod tym linkiem znajduje się plik JSON, który jest niczym innym jak całą naszą kolekcją requestów. Gdy wejdzie na niego inny użytkownik z zainstalowaną wtyczką “Postman” – cała kolekcja automatycznie zostanie u niego załadowana lub zaktualizowana. Dane tam zawarte możemy na bieżąco aktualizować klikając w przycisk “Update link”. To naprawdę poręczna rzecz, którą warto dorzucić np. do README.
Ale to nie wszystko. Gdy już pieczołowicie, z biegiem czasu przygotujemy naszą bogatą kolekcję requestów, a do tego dodając każdy z nich nadamy mu sensowną nazwę i wzbogacimy o opis, to jednym kliknięciem możemy wygenerować bardzo przyzwoitą dokumentację w HTML. I to nawet responsywną. Jak to zrobić?
Wystarczy w menu kolekcji wybrać opcję “View in web” – pozwoli nam to obejrzeć podgląd. Gdy będziemy nim usatysfakcjonowani, wystarczy wybrać opcję “Publish docs”, która pozwala nam udostępnić dokumentację pod unikalnym linkiem. I co ważne – będzie ona się aktualizować razem z naszą kolekcją w aplikacji – wystarczy, że zapiszemy zmiany w którymś z naszych requestów.
Dla każdego endpointa widzimy pełny adres URL, listę nagłówków, a w przypadku requestów POST mamy również pokazane wysyłane dane. Po prawej stronie każdej metody mamy gotową do skopiowania wersję cURL, ale możemy ją również łatwo zmienić na gotowe zapytania w jQuery, Ruby, Go, PHP i innych językach.
TL;DR
Jeśli pracujesz nad rozwojem API w swojej aplikacji to zdecydowanie zapoznaj się z Postmanem. Pozwoli ci to skupić się na logice aplikacji zamiast na narzędziach oraz zautomatyzować tworzenie podstawowej dokumentacji. Stanie się również pewnym źródłem aktualnych informacji, głównie dzięki temu, że przekazanie kolekcji innym członkom zespołu jest bajecznie proste, a dokumentacja aktualizuje się sama podczas pracy.
Ponadto, w aktualnej wersji jest możliwe mockowanie serwerów oraz testowanie API, co czyni z Postmana komplementarne narzędzie do pracy przy tego typu projektach.
