Insomnia, klient API z wyborem miejsca danych

Insomnia, czyli klient API, w którym wybierasz, gdzie leżą dane

Klienty API dzielą się dziś na te wymagające konta i synchronizacji w chmurze oraz te trzymające wszystko lokalnie. Insomnia pozwala wybrać, i to na poziomie pojedynczego projektu, co odróżnia go od większości konkurencji.

Do wyboru są trzy tryby: chmura z synchronizacją między urządzeniami, dysk lokalny bez wysyłania czegokolwiek oraz repozytorium Git jako miejsce przechowywania kolekcji. Ten trzeci jest najciekawszy dla zespołów, bo zamienia kolekcje w pliki podlegające przeglądowi.

Trzy tryby przechowywania

Wybór trybu warto przemyśleć przy zakładaniu projektu, bo określa on sposób pracy zespołu.

Tryb chmurowy synchronizuje kolekcje między urządzeniami i osobami. Jest najwygodniejszy i oznacza, że treść zapytań, w tym adresy wewnętrzne i struktura interfejsu, leży po stronie dostawcy. Przy interfejsach publicznych to bez znaczenia, przy wewnętrznych bywa przedmiotem rozmowy z działem bezpieczeństwa.

Tryb lokalny trzyma wszystko na dysku i nie wysyła niczego. Sprawdza się przy pracy indywidualnej i przy wymogach zgodności, a jego kosztem jest brak dzielenia się pracą inaczej niż przez eksport pliku.

Tryb oparty o repozytorium łączy zalety obu. Kolekcje leżą jako pliki w Twoim repozytorium, więc podlegają przeglądowi, mają historię zmian i działają u wszystkich, którzy mają dostęp do kodu. Zmiana w kolekcji przechodzi tą samą drogą co zmiana w kodzie.

Ostatni tryb jest najbardziej sensowny dla zespołu, ale wymaga dyscypliny. Sekrety nie mogą trafić do repozytorium, więc środowiska z tokenami trzeba oznaczyć jako prywatne albo pobierać wartości z sejfu.

Kolekcje, środowiska i zmienne

Struktura jest tu podobna jak w innych narzędziach tej kategorii: zapytania grupujesz w kolekcje, a wartości zmienne trzymasz w środowiskach.

{{ _.baseUrl }}/api/zamowienia/{{ _.orderId }}

Authorization: Bearer {{ _.token }}

Środowiska mogą dziedziczyć, więc wartości wspólne zapisujesz raz na poziomie nadrzędnym, a różnice w środowiskach potomnych. To upraszcza sytuację, w której masz cztery środowiska różniące się dwoma wartościami.

Zmienne mogą pochodzić z odpowiedzi poprzedniego zapytania, co rozwiązuje najczęstszy problem: token wygasający co godzinę. Zamiast przeklejać go ręcznie, wskazujesz pole w odpowiedzi zapytania logującego, a narzędzie podstawia je automatycznie.

Warto tu ustawić jedną rzecz od początku: żaden adres nie jest wpisany na sztywno. Zapytanie napisane na pięć minut zostaje na dwa lata, a kolekcja z wpisanymi adresami przestaje działać przy pierwszej zmianie środowiska.

Sejfy i sekrety

Jedenasta wersja dołożyła integrację z zewnętrznymi sejfami, co zmienia sposób pracy z tokenami w zespole.

Wcześniej sekret trzeba było albo wpisać w środowisko, albo pobierać ręcznie. Pierwsze podejście kończyło się tokenem w pliku, drugie było uciążliwe. Pobieranie wartości z sejfu w chwili wysłania zapytania rozwiązuje oba problemy: w kolekcji leży odwołanie, a nie wartość.

To ma znaczenie zwłaszcza w trybie opartym o repozytorium. Kolekcja trafia do repozytorium razem z kodem, więc odwołanie do sejfu jest tam bezpieczne, a wpisany token nie.

Przy pracy indywidualnej wystarcza oznaczenie zmiennej jako prywatnej, dzięki czemu nie trafia do eksportu. To rozróżnienie ma znaczenie przy dzieleniu się kolekcją, bo chcesz przekazać strukturę zapytań, a nie swoje poświadczenia.

Testy i uruchamianie kolekcji

Poza wysyłaniem zapytań narzędzie pozwala pisać testy sprawdzające odpowiedzi.

insomnia.test('Zamowienie oplacone', () => {
  insomnia.expect(insomnia.response.code).to.eql(200)

  const dane = insomnia.response.json()
  insomnia.expect(dane.status).to.eql('oplacone')
  insomnia.expect(dane.pozycje).to.be.an('array').that.is.not.empty
})

Ten sam skrypt po odpowiedzi nadaje się do przeniesienia wartości do środowiska, co rozwiązuje problem tokenu wygasającego w trakcie przebiegu kolekcji.

insomnia.test('Zapisz token', () => {
  insomnia.expect(insomnia.response.code).to.eql(200)
  insomnia.environment.set('token', insomnia.response.json().access_token)
})

Warto rozróżnić dwa miejsca zapisu. Zapis do środowiska wybranego dotyczy tylko jego, a zapis do środowiska bazowego widzą wszystkie środowiska potomne. Token dostępowy należy do pierwszego, adres bazowy usługi zwykle do drugiego.

Uruchomienie całej kolekcji sprawdza kolejno wszystkie zapytania, co daje prosty test interfejsu po wdrożeniu. Wykrywa to najczęstszą klasę problemów przy zmianach w zapleczu: pole, które zniknęło albo zmieniło nazwę.

Do potoku budowania służy osobne narzędzie wiersza poleceń, przyjmujące nazwę kolekcji i wskazanie środowiska. Bez tego kroku testy pozostają rzeczą uruchamianą ręcznie, czyli w praktyce rzadko.

brew install inso
inso run collection "Zamowienia" --env "Produkcja"
inso run test "Kontrakt zamowien" --env "Produkcja"

Warto wiedzieć, że tego narzędzia nie instaluje się dziś z rejestru npm. Pakiet o tej nazwie istnieje, ale ostatnie wydanie pochodzi z 2022 roku, więc instalacja stamtąd daje wersję sprzed kilku lat. Aktualne drogi to menedżer pakietów systemu, gotowy plik wykonywalny albo obraz kontenera, i ten ostatni jest zwykle najwygodniejszy w potoku. W obrazie nie ma ustawionego katalogu roboczego, więc do podmontowanego katalogu trzeba dopisać przełącznik wskazujący miejsce pracy, inaczej narzędzie szuka kolekcji w katalogu głównym kontenera.

docker run --rm -v "$PWD:/var/temp" kong/inso:latest \
  run collection "Zamowienia" --env "Produkcja" -w /var/temp

Warto pamiętać, że to nie zastępuje testów w kodzie. Sprawdzenie kształtu odpowiedzi po wdrożeniu jest przydatne, a logikę biznesową testuje się bliżej niej samej.

Projektowanie interfejsu

Narzędzie obsługuje też pracę z opisem interfejsu w standardowym formacie, z podglądem i sprawdzaniem poprawności.

Ta funkcja przydaje się przy podejściu, w którym opis powstaje przed implementacją i służy za kontrakt między zespołami. Front może wtedy pracować na atrapie generowanej z opisu, zanim zaplecze będzie gotowe.

Praktyczna uwaga: opis interfejsu ma wartość tylko wtedy, gdy jest utrzymywany. Plik napisany na starcie projektu i porzucony po trzech miesiącach jest gorszy od jego braku, bo wprowadza w błąd. Jeśli zespół nie planuje generować z niego kodu ani testów, lepiej oprzeć się na dobrze utrzymanej kolekcji.

Poza tym narzędzie obsługuje protokoły spoza zwykłego HTTP: GraphQL z podglądem schematu, gniazda sieciowe, zdarzenia wysyłane przez serwer oraz wywołania w formacie binarnym. Ten ostatni bywa argumentem rozstrzygającym, bo obsługują go nieliczne narzędzia graficzne.

Praca zespołowa na repozytorium

Tryb oparty o repozytorium wymaga kilku ustaleń, bez których zamienia się w źródło konfliktów przy scalaniu.

Pierwsze dotyczy podziału na projekty. Jeden duży projekt z zapytaniami wszystkich zespołów oznacza, że każda zmiana dotyka pliku, który edytują też inni. Podział według obszarów odpowiedzialności ogranicza to do minimum.

Drugie to nazewnictwo. Zapytania nazwane opisowo, na przykład „utworz zamowienie z platnoscia odroczona", są czytelne w różnicy zmian. Nazwy w rodzaju „test 3" nie mówią nic ani w narzędziu, ani w przeglądzie.

Trzecie to sposób pracy nad zmianą. Zmiana w kolekcji idzie tą samą drogą co zmiana w kodzie: własna gałąź, propozycja zmian, przegląd. To brzmi ciężko przy dodaniu jednego zapytania, a chroni przed sytuacją, w której ktoś zmienia adres bazowy i kolekcja przestaje działać wszystkim.

Czwarte to sprzątanie. Kolekcje rosną, a zapytania do wycofanych punktów końcowych zostają, bo nikt nie ma odwagi ich skasować. Przegląd raz na kwartał, podczas którego usuwa się to, czego nikt nie uruchamiał od pół roku, utrzymuje kolekcję w stanie użytecznym.

Migracja z innego narzędzia

Kolekcja budowana przez dwa lata jest zwykle głównym powodem, dla którego zespoły zostają przy narzędziu, którego nie lubią. Warto wiedzieć, jak duży jest ten koszt naprawdę.

Import z formatów innych klientów działa i przenosi zapytania, nagłówki oraz zmienne środowiskowe. To pokrywa większość zawartości typowej kolekcji, więc sam przenos jest kwestią minut.

Rzeczy, które wymagają uwagi, to skrypty. Składnia różni się między narzędziami, więc kod pobierający token z odpowiedzi trzeba przepisać. Przy kolekcji z pięcioma takimi miejscami to godzina pracy, przy kolekcji z pięćdziesięcioma warto rozważyć, czy wszystkie są jeszcze potrzebne.

Drugą rzeczą są sekrety. Import nie przeniesie wartości ze środowisk oznaczonych jako prywatne, i słusznie, więc trzeba je ustawić od nowa. To dobry moment na zrotowanie tokenów, skoro i tak dotyka się konfiguracji.

Trzecią jest ustalenie trybu przechowywania przed importem. Wrzucenie kolekcji do projektu chmurowego, a potem przenoszenie jej do trybu opartego o repozytorium, oznacza robotę dwa razy.

Insomnia kontra alternatywy

Wybór między pierwszymi trzema wierszami sprowadza się do trzech pytań. Czy potrzebujesz protokołów poza HTTP, bo wtedy pierwszy wiersz ma najszerszą obsługę. Czy chcesz pracować całkowicie bez usługi zewnętrznej, bo wtedy drugi jest do tego zbudowany. Czy zależy Ci na dostępie z przeglądarki bez instalacji, bo wtedy trzeci.

Wszystkie trzy pozwalają trzymać kolekcje w repozytorium, więc pod tym względem różnice są mniejsze, niż wynikałoby z materiałów producentów. Decydujące bywa przyzwyczajenie zespołu, bo narzędzie, którego nikt nie chce otworzyć, nie pomoże niezależnie od możliwości.

Wtyczki i rozszerzanie

Narzędzie pozwala dopisać własne wtyczki, co przydaje się przy rzeczach specyficznych dla Twojego zaplecza.

Najczęstsze zastosowanie to własny sposób podpisywania żądań. Interfejsy wymagające podpisu opartego o klucz i znacznik czasu nie dadzą się obsłużyć samymi nagłówkami, a wtyczka licząca podpis przed wysłaniem rozwiązuje to raz dla całego zespołu.

Drugie to własne formaty odpowiedzi. Zaplecze zwracające dane w formacie binarnym albo skompresowanym wymaga przekształcenia, żeby dało się je obejrzeć, i to również mieści się we wtyczce.

Trzecie to generowanie wartości. Identyfikatory o określonym formacie, dane testowe zgodne z regułami walidacji, znaczniki czasu w nietypowej postaci: wszystko, co powtarza się przy każdym zapytaniu.

Warto natomiast zachować umiar. Wtyczka to kod bez testów, uruchamiany na maszynach zespołu, a jej utrzymanie spada na osobę, która ją napisała. Przy rzeczach, które da się załatwić zmienną albo skryptem przy zapytaniu, wtyczka jest rozwiązaniem nieproporcjonalnym do problemu.

Typowe błędy

Pierwszy to adresy wpisane na sztywno zamiast zmiennych środowiskowych. Kolekcja przestaje działać po zmianie środowiska, a poprawianie zapytań ręcznie trwa dłużej niż ustawienie zmiennej na początku.

Drugi to tokeny w kolekcji trafiającej do repozytorium. Wartość zapisana w środowisku zostaje w historii zmian, więc po odkryciu wymaga rotacji.

Trzeci to wybór trybu chmurowego bez sprawdzenia wymogów. Przy interfejsach wewnętrznych warto to ustalić przed założeniem projektu, bo zmiana trybu później oznacza przeniesienie kolekcji.

Czwarty to kolekcja testująca wyłącznie ścieżkę poprawną. Zmiana w obsłudze błędów przechodzi wtedy niezauważona, a to tam kryje się większość niespodzianek.

Piąty to opis interfejsu, którego nikt nie utrzymuje. Nieaktualny plik wprowadza w błąd skuteczniej niż jego brak.

Szósty to testy uruchamiane wyłącznie ręcznie. Bez wpięcia w potok budowania przestają być używane w ciągu miesiąca.

Kiedy klient graficzny nie jest potrzebny

Warto uczciwie powiedzieć, że nie każde zadanie wymaga takiego narzędzia, bo instalowanie aplikacji do sprawdzenia jednego punktu końcowego to nadmiar.

Pojedyncze żądanie sprawdzisz szybciej poleceniem w terminalu, zwłaszcza gdy interesuje Cię tylko status i kilka pól. To samo dotyczy szybkiego sprawdzenia, czy usługa w ogóle odpowiada.

Zadania powtarzalne należą do skryptów. Codzienne sprawdzenie kilkunastu punktów końcowych to plik uruchamiany harmonogramem, a nie kolekcja, którą ktoś musi otworzyć i kliknąć.

Testy logiki biznesowej należą do kodu, bliżej tej logiki. Sprawdzenie, czy rabat naliczył się poprawnie, jest testem jednostkowym, nie zapytaniem w kliencie API.

Klient graficzny zarabia na siebie przy trzech rzeczach: przeglądaniu długich odpowiedzi, pracy z kolekcją utrzymywaną przez zespół i eksplorowaniu cudzego interfejsu, którego jeszcze nie znasz. Przy tych zastosowaniach różnica wobec terminala jest odczuwalna i wtedy warto go mieć.

FAQ

Czy Insomnia jest darmowa?

Podstawowe użycie jest darmowe, a plany płatne dodają współpracę zespołową, wyższe limity i funkcje organizacyjne. Aktualne progi warto sprawdzić na stronie producenta, bo model rozliczenia bywa zmieniany.

Czy da się pracować bez konta i bez chmury?

Tak, tryb lokalny trzyma wszystko na dysku i nie wysyła niczego. Tryb oparty o repozytorium przechowuje kolekcje jako pliki w Twoim repozytorium, co przy pracy zespołowej jest zwykle lepszym wyborem niż chmura dostawcy.

Czym różni się od Bruno?

Bruno jest zbudowane wokół jednej idei: kolekcje jako pliki w repozytorium, bez usługi po stronie serwera. Insomnia daje wybór między trzema trybami i obsługuje więcej protokołów, w tym wywołania w formacie binarnym, kosztem większej aplikacji.

Czy obsługuje gRPC i GraphQL?

Tak, oba mają osobne widoki. GraphQL pobiera schemat z punktu końcowego i podpowiada pola, a przy wywołaniach binarnych narzędzie odczytuje definicje usług, co jest rzadkie wśród klientów graficznych.

Czy kolekcję można uruchomić w potoku budowania?

Tak, przez narzędzie wiersza poleceń przyjmujące kolekcję i środowisko. To pozwala sprawdzać po wdrożeniu, czy najważniejsze ścieżki interfejsu odpowiadają tak jak wcześniej.

Dokumentacja stoi na stronie Kong, a kod źródłowy w repozytorium na GitHubie.