Hoppscotch, klient API w przeglądarce

Hoppscotch, klient API, który otwiera się w sekundę

Klienty API urosły przez lata z narzędzia do wysyłania żądań w platformę z kontem, synchronizacją, obszarami roboczymi i aktualizatorem. Hoppscotch idzie w drugą stronę: otwierasz zakładkę w przeglądarce, wysyłasz żądanie i widzisz odpowiedź.

To projekt otwarty, który da się uruchomić we własnej infrastrukturze, a przy pracy indywidualnej działa bez zakładania konta. Poza żądaniami HTTP obsługuje GraphQL, gniazda sieciowe, zdarzenia wysyłane przez serwer i protokół publikacji subskrypcji.

Dlaczego przeglądarka ma znaczenie

Uruchomienie w przeglądarce to nie jest tylko wygoda. Zmienia dwie rzeczy praktyczne.

Pierwsza to czas dojścia do pracy. Narzędzie bez instalacji i bez logowania jest dostępne od razu, także na cudzym komputerze i na maszynie, na której nie masz uprawnień do instalowania oprogramowania.

Druga to miejsce, z którego wychodzi żądanie. Klient przeglądarkowy wysyła je z Twojej przeglądarki, więc dotyczą go zasady pochodzenia i dostęp do sieci lokalnej. To pomaga przy testowaniu usług w intranecie, a przeszkadza przy usługach bez odpowiednich nagłówków. Do tych drugich służy pośrednik przekazujący żądanie, uruchamiany lokalnie albo dostarczony przez usługę.

Warto tę różnicę rozumieć, bo najczęstszy problem przy pierwszym użyciu to błąd polityki pochodzenia, który wygląda jak awaria narzędzia, a jest normalnym zachowaniem przeglądarki.

Kolekcje i środowiska

Zapytania grupuje się w kolekcje, a wartości zmienne trzymasz w środowiskach. Ten podział jest wspólny dla wszystkich narzędzi tej kategorii i to on decyduje o tym, czy kolekcja jest użyteczna po miesiącu.

<<baseUrl>>/api/zamowienia/<<orderId>>

Authorization: Bearer <<token>>

Środowisko lokalne, testowe i produkcyjne różnią się wtedy tylko wartościami, a nie treścią zapytań. Zmiana środowiska jednym wyborem z listy przełącza wszystkie zapytania w kolekcji.

Dwie zasady sprawiają, że to się nie rozjeżdża. Pierwsza: żaden adres nie jest wpisany na sztywno, nawet w zapytaniu pisanym na pięć minut, bo takie zapytania zostają na lata. Druga: sekrety trafiają wyłącznie do środowisk oznaczonych jako prywatne, nigdy do kolekcji, która idzie do repozytorium.

Kolekcje da się eksportować i importować, w tym z formatów innych narzędzi. To ważne przy przenoszeniu istniejącej pracy, bo kolekcja budowana przez dwa lata jest zwykle głównym powodem, dla którego zespoły zostają przy narzędziu, którego nie lubią.

Skrypty przed i po żądaniu

Zapytania rzadko są niezależne. Zwykle trzeba się najpierw zalogować, wziąć token i użyć go w kolejnych wywołaniach.

pw.env.set("token", pw.response.body.access_token)

pw.test("Status 200", () => {
  pw.expect(pw.response.status).toBe(200)
})

pw.test("Zamowienie ma pozycje", () => {
  pw.expect(pw.response.body.items).toBeType("array")
  pw.expect(pw.response.body.items.length).not.toBe(0)
})

Skrypt po odpowiedzi zapisuje token do środowiska, więc kolejne zapytania korzystają z niego automatycznie. Ten wzorzec pokrywa większość potrzeb i pozwala uruchomić całą kolekcję jednym poleceniem, bez ręcznego przeklejania.

Testy w tym samym miejscu zamieniają kolekcję w prosty zestaw sprawdzeń. To nie zastępuje testów w kodzie, ale wystarcza do sprawdzenia, czy interfejs po wdrożeniu odpowiada tak jak wcześniej.

Skrypt przed żądaniem przydaje się do rzeczy liczonych na bieżąco: podpisu, znacznika czasu, identyfikatora korelacji. Trzymaj go krótkim, bo skrypt na trzydzieści linii w kliencie API to sygnał, że to zadanie należy do kodu.

pw.env.set("timestamp", String(Date.now()))
pw.env.set("correlationId", crypto.randomUUID())

const baza = pw.env.get("baseURL")
pw.env.set("pelnyAdres", pw.env.resolve("<<baseURL>>/api/v2"))

Warto znać różnicę między trzema sposobami odczytu. Zwykły odczyt zwraca wartość taką, jaka jest w środowisku, wraz z ewentualnymi odwołaniami do innych zmiennych. Odczyt rozwijający podstawia te odwołania, a osobna funkcja rozwija cały wzorzec podany jako tekst. Pomylenie ich kończy się adresem zawierającym dosłowne nawiasy zamiast wartości.

Uruchamianie z wiersza poleceń

Kolekcja uruchamiana ręcznie sprawdza się przy diagnozowaniu, a nie przy pilnowaniu jakości. Do tego drugiego służy uruchomienie w potoku budowania.

npm i -g @hoppscotch/cli
hopp test kolekcja.json -e srodowisko.json

W potoku budowania wygląda to jak każdy inny krok, a kod wyjścia różny od zera zatrzymuje wdrożenie.

- name: Testy interfejsu
  run: |
    npm i -g @hoppscotch/cli
    hopp test kolekcje/publiczne.json -e srodowiska/produkcja.json

Taki układ daje proste testy interfejsu po wdrożeniu: kolekcja przechodzi przez najważniejsze ścieżki i zgłasza błąd, gdy odpowiedź się zmieni. To wykrywa najczęstszą klasę problemów przy zmianach w zapleczu, czyli pole, które zniknęło albo zmieniło nazwę.

Warunkiem jest trzymanie kolekcji w repozytorium, a nie wyłącznie w koncie użytkownika. Plik w repozytorium podlega przeglądowi, ma historię zmian i działa u wszystkich, a kolekcja w czyimś koncie znika razem z tą osobą.

Praca z GraphQL

Zapytania GraphQL mają w tym narzędziu osobny widok, bo różnią się od zwykłych żądań na tyle, że wspólny formularz byłby niewygodny.

query PobierzZamowienie($id: ID!) {
  zamowienie(id: $id) {
    numer
    status
    pozycje {
      nazwa
      ilosc
    }
  }
}

Zmienne podajesz osobno, a narzędzie pobiera schemat z punktu końcowego, więc podpowiada dostępne pola i zgłasza błąd, zanim wyślesz zapytanie o pole, którego nie ma. To najbardziej użyteczna część pracy z tym protokołem, bo dokumentacja bywa niekompletna, a schemat zawsze jest aktualny.

Warto pamiętać o różnicy w obsłudze błędów. Odpowiedź GraphQL potrafi mieć status dwieście i jednocześnie zawierać błędy w osobnym polu, więc test sprawdzający wyłącznie status przepuści zapytanie, które nic nie zwróciło.

pw.test("Brak bledow GraphQL", () => {
  pw.expect(typeof pw.response.body.errors).toBe("undefined")
})

Przy zapleczu opartym o GraphQL warto mieć w kolekcji zapytanie pobierające schemat. Uruchamiane po wdrożeniu wykrywa usunięcie pola, zanim zauważy to front.

Gniazda i strumienie zdarzeń

Poza zwykłymi żądaniami narzędzie obsługuje połączenia trwałe, co przydaje się przy aplikacjach z powiadomieniami i przy strumieniowaniu odpowiedzi modelu.

Widok gniazd pozwala nawiązać połączenie, wysłać wiadomość i obejrzeć wszystko, co przychodzi z drugiej strony. To rozwiązuje najbardziej uciążliwy etap diagnozowania takich połączeń, gdzie bez narzędzia trzeba pisać własną stronę testową.

Zdarzenia wysyłane przez serwer mają osobny widok pokazujący strumień na bieżąco. Przy punkcie końcowym strumieniującym odpowiedź modelu, zbudowanym na przykład w Hono, pozwala to sprawdzić, czy fragmenty faktycznie wychodzą po kawałku, a nie w całości na końcu.

Trzecim obsługiwanym protokołem jest publikacja subskrypcji używana w rozwiązaniach z pomiarami i urządzeniami. To niszowe zastosowanie, ale obecność tych trzech protokołów w jednym narzędziu oszczędza instalowania trzech osobnych.

Wdrożenie u siebie i ceny

Wdrożenie we własnej infrastrukturze jest tu główną przewagą wobec narzędzi zamkniętych. Zapytania, kolekcje i sekrety zostają na Twoim serwerze, co przy interfejsach dotykających danych osobowych bywa wymogiem, a nie preferencją.

Warto przy tym pamiętać o kosztach niewidocznych w cenniku: serwer, aktualizacje, kopie zapasowe i uwierzytelnianie podpięte pod istniejący system. Przy zespole pięcioosobowym te koszty zwykle przewyższają abonament, a przy pięćdziesięcioosobowym proporcja się odwraca. Warunkiem, który przesądza sprawę niezależnie od rachunku, jest wymóg, żeby dane nie opuszczały infrastruktury firmy.

Hoppscotch kontra alternatywy

Ostatni wiersz bywa niesłusznie pomijany. Jedno żądanie sprawdzisz poleceniem w terminalu szybciej niż otwierając cokolwiek, a przy skryptach to jedyne sensowne rozwiązanie. Klient graficzny zarabia na siebie przy przeglądaniu długich odpowiedzi, przy pracy z kolekcją i przy dzieleniu się nią z zespołem.

Wybór między pierwszymi dwoma wierszami sprowadza się do pytania o format przechowywania. Jeśli chcesz kolekcje w repozytorium jako pliki podlegające przeglądowi, drugi wiersz jest do tego zbudowany. Jeśli zależy Ci na dostępie z przeglądarki i pracy zespołowej w jednym miejscu, pierwszy.

Kolekcja jako dokumentacja interfejsu

Dobrze utrzymana kolekcja jest najbardziej aktualną dokumentacją interfejsu, jaką zespół ma pod ręką. Dokumentacja pisana osobno starzeje się w miesiąc, a kolekcja starzeje się dopiero wtedy, gdy przestaje działać, co ktoś zauważa od razu.

Żeby to działało, kolekcja potrzebuje kilku rzeczy poza samymi zapytaniami. Opis przy każdym zapytaniu mówiący, do czego służy i kiedy się je wywołuje. Przykładowe wartości w zmiennych, żeby nowa osoba mogła uruchomić je bez pytania. Zapytania pokazujące też przypadki błędne, bo kod błędu i kształt odpowiedzi błędnej są częścią kontraktu.

Warto ustawić kolejność zapytań tak, żeby dało się przejść przez nie z góry na dół i zobaczyć cały przepływ: logowanie, utworzenie zasobu, odczyt, modyfikacja, usunięcie. Taka kolekcja tłumaczy działanie interfejsu lepiej niż akapit prozy.

Osobną korzyścią jest zgłaszanie błędów. Zapytanie odtwarzające problem, dołączone do zgłoszenia, oszczędza rundę pytań o to, jak dokładnie ktoś wywołał interfejs.

Uwierzytelnianie i sekrety

Większość interfejsów wymaga tokenu, a sposób jego zdobycia bywa najbardziej uciążliwym elementem pracy.

Narzędzie obsługuje standardowe schematy uwierzytelniania w osobnej zakładce, więc nie trzeba budować nagłówka ręcznie. Przy przepływie z przekierowaniem warto jednak pamiętać, że część kroków dzieje się w przeglądarce i wymaga poprawnie ustawionego adresu powrotnego po stronie dostawcy tożsamości.

Praktyczny wzorzec przy tokenach krótkotrwałych wygląda tak: osobne zapytanie logujące zapisuje token do środowiska, a wszystkie pozostałe używają zmiennej. Odświeżenie sprowadza się wtedy do jednego kliknięcia zamiast do przeklejania wartości.

Sekrety trzymaj w zmiennych oznaczonych jako sekretne, które nie trafiają do eksportu. To rozróżnienie ma znaczenie przy dzieleniu się kolekcją: chcesz przekazać strukturę zapytań, a nie swój token do środowiska produkcyjnego. Przy pracy w zespole warto ustalić, że każdy używa własnych poświadczeń, bo wspólny token uniemożliwia ustalenie, kto wykonał daną operację.

Typowe błędy

Pierwszy to adresy wpisane na sztywno w zapytaniach. Kolekcja przestaje działać po zmianie środowiska, a poprawianie dwudziestu zapytań ręcznie zajmuje więcej czasu niż ustawienie zmiennej na początku.

Drugi to sekrety w kolekcji eksportowanej do repozytorium. Token wpisany w nagłówku zostaje w historii zmian i po odkryciu wymaga rotacji.

Trzeci to traktowanie błędu polityki pochodzenia jak awarii narzędzia. To normalne zachowanie przeglądarki i rozwiązuje je pośrednik albo odpowiednie nagłówki po stronie usługi.

Czwarty to trzymanie kolekcji wyłącznie w koncie użytkownika. Wiedza o tym, jak wywołać interfejs, znika wtedy razem z osobą, która odchodzi z zespołu.

Piąty to rozbudowane skrypty w kliencie. Logika, która urosła do kilkudziesięciu linii, należy do kodu z testami, a nie do narzędzia bez kontroli wersji.

Szósty to testowanie wyłącznie ścieżki poprawnej. Kolekcja sprawdzająca tylko sytuacje, w których wszystko działa, nie wykryje zmiany w obsłudze błędów, a to tam kryje się większość niespodzianek.

FAQ

Czy Hoppscotch jest darmowy?

Wersja przeglądarkowa do pracy indywidualnej jest darmowa i nie wymaga konta. Wersja społecznościowa do wdrożenia we własnej infrastrukturze również. Płatny plan w chmurze nazywa się Organization i kosztuje osiem dolarów za osobę miesięcznie przy rozliczeniu miesięcznym albo sześć przy rocznym. Wersja Enterprise do wdrożenia u siebie ma podaną cenę: dziewiętnaście dolarów za osobę miesięcznie albo sto dziewięćdziesiąt za osobę rocznie.

Czym różni się od Postmana?

Jest znacznie lżejszy, działa w przeglądarce bez instalacji i można go uruchomić na własnym serwerze. Postman ma więcej funkcji i integracji, ale wymaga konta, waży więcej i przy zespole kosztuje wyraźnie więcej. Do codziennego wysyłania żądań różnica w możliwościach jest niewielka.

Czy obsługuje GraphQL?

Tak, z osobnym widokiem dla zapytań i przeglądaniem schematu pobranego z punktu końcowego. Poza tym obsługuje gniazda sieciowe, zdarzenia wysyłane przez serwer i protokół publikacji subskrypcji, więc pokrywa większość protokołów spotykanych poza zwykłym HTTP.

Czy da się uruchomić kolekcję w potoku budowania?

Tak, przez narzędzie wiersza poleceń przyjmujące plik kolekcji i plik środowiska. To pozwala sprawdzać po wdrożeniu, czy najważniejsze ścieżki interfejsu odpowiadają tak jak wcześniej, co wykrywa zmiany łamiące zgodność.

Kiedy lepiej wybrać coś innego?

Gdy zespół chce trzymać kolekcje jako pliki w repozytorium i pracować bez usługi po stronie serwera, wtedy Bruno jest do tego zbudowane. Przy jednorazowym sprawdzeniu jednego żądania szybsze bywa polecenie w terminalu, a przy rozbudowanym procesie w dużej organizacji wygrywa narzędzie z większym zbiorem integracji.

Dokumentacja stoi na stronie projektu, a instrukcja wdrożenia we własnej infrastrukturze w poradniku samodzielnego hostowania.