Czego szukasz?

Wpisz temat, narzędzie lub problem do rozwiązania.

← Wszystkie artykuły

cURL: jak testować API z terminala

Dwa metalowe złącza połączone jasnym paskiem papieru na terakotowym tle

API odpowiada w przeglądarce, ale integracja nadal kończy się błędem. cURL pozwala zobaczyć, co dokładnie wysyłasz i co zwraca serwer: metodę, nagłówki, treść oraz kod HTTP. Najważniejsza pułapka: poprawne zakończenie programu nie musi oznaczać poprawnej odpowiedzi aplikacji.

Poniższe polecenia są przeznaczone dla Bash. W Windows uruchamiaj curl.exe, aby nie trafić na alias powłoki, a wielowierszowe komendy połącz w jedną linię. Zaczniemy od odczytu, a zapis sprawdzimy na lokalnym serwerze demonstracyjnym.

Sprawdź wersję i pierwszy odczyt

curl --version
curl --silent --show-error --max-time 15 https://trybtechniczny.pl/wp-json/

Pierwsze polecenie pokazuje wersję programu i obsługiwane protokoły. Drugie pobiera publiczny indeks API WordPressa. Nie wymaga logowania ani nie zmienia danych. Jeśli serwer ogranicza REST API, odpowiedź może zależeć od jego konfiguracji.

--silent wyłącza pasek postępu, a --show-error pozostawia komunikat błędu. Nie używaj samego wyciszenia w zadaniu cyklicznym: puste wyjście bez przyczyny utrudnia diagnozę. Podstawy endpointów i metod wyjaśnia poradnik REST API.

Oddziel nagłówki od treści

Przy diagnostyce zapisz oba elementy osobno:

curl --silent --show-error \
  --dump-header headers.txt \
  --output response.json \
  --write-out 'HTTP %{http_code}\n' \
  --max-time 15 \
  https://trybtechniczny.pl/wp-json/

Pliki o podanych nazwach zostaną zastąpione, dlatego pracuj w katalogu testowym. Rozszerzenie .json nie gwarantuje formatu odpowiedzi. Reverse proxy może zwrócić HTML, choć endpoint zwykle zwraca JSON. Sprawdź Content-Type oraz początek pliku przed uruchomieniem parsera.

Opcja -i dołącza nagłówki do standardowego wyjścia. Przydaje się do oglądania odpowiedzi, ale taki połączony strumień nie jest już czystym JSON-em. -I wykonuje żądanie HEAD; nie jest identycznym testem jak GET z pominiętym wyświetlaniem treści. Nie każdy endpoint obsługuje obie metody tak samo.

Do przejrzenia niesekretnej odpowiedzi możesz użyć formattera JSON. Sam poprawny format nie potwierdza zgodności danych z oczekiwanym schematem.

Kod HTTP a kod zakończenia cURL

Domyślnie cURL może zakończyć się kodem 0 po otrzymaniu HTTP 404. Transfer się udał, chociaż zasobu nie znaleziono. W automatyzacji często potrzebujesz innego zachowania:

curl --silent --show-error --fail-with-body \
  --connect-timeout 5 --max-time 20 \
  https://trybtechniczny.pl/wp-json/

--fail-with-body zachowuje treść odpowiedzi i dla odpowiedzi błędnych HTTP daje błąd procesu. Opcja jest dostępna od cURL 7.76.0. Przy starszym programie sprawdź możliwość aktualizacji lub osobno oceniaj kod HTTP. Nie zakładaj, że każda maszyna ma identyczny zestaw opcji.

Wynik Co oznacza w diagnostyce
HTTP 401 lub 403 Sprawdź uwierzytelnienie i uprawnienia
HTTP 404 Sprawdź ścieżkę oraz identyfikator zasobu
HTTP 429 Osiągnięto ograniczenie żądań
Kod procesu 22 z opcją fail Odpowiedź HTTP została uznana za błąd
Kod procesu 28 Przekroczono limit czasu

W Bash kod ostatniego polecenia odczytasz przez echo $?, a w PowerShell przez $LASTEXITCODE. Zrób to od razu, zanim uruchomisz kolejną komendę. Przekazanie wyniku do innego programu może dodatkowo zmienić sposób oceny całego potoku.

Wyślij JSON z pliku

Zamiast walczyć z cudzysłowami powłoki, utwórz payload.json:

{"name":"demo","enabled":true}

Opcja --json @payload.json wysyła plik jako JSON i ustawia odpowiednie nagłówki. Nie sprawdza jednak, czy zawartość pliku jest poprawnym JSON-em. Jest dostępna od wersji 7.82.0.

Poniższy prosty serwer przyjmuje wyłącznie lokalne połączenia. Zapisz go jako server.py i uruchom python server.py w osobnym terminalu:

from http.server import BaseHTTPRequestHandler, HTTPServer
import json
class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        status = 404 if self.path == '/missing' else 200
        body = json.dumps({'path': self.path, 'status': status}).encode()
        self.send_response(status)
        self.send_header('Content-Type', 'application/json')
        self.end_headers()
        self.wfile.write(body)
    def do_POST(self):
        size = int(self.headers.get('Content-Length', 0))
        if size > 4096:
            self.send_error(413)
            return
        data = self.rfile.read(size)
        try:
            value = json.loads(data)
        except ValueError:
            self.send_error(400)
            return
        self.send_response(200)
        self.send_header('Content-Type', 'application/json')
        self.end_headers()
        self.wfile.write(json.dumps({'received': value}).encode())
if __name__ == '__main__':
    HTTPServer(('127.0.0.1', 8765), Handler).serve_forever()

Następnie wykonaj:

curl --silent --show-error --fail-with-body \
  --json @payload.json http://127.0.0.1:8765/echo

Serwer odsyła otrzymany obiekt, bez zapisywania go w bazie. To demonstracja, nie gotowy publiczny backend. Po teście zatrzymaj go przez Ctrl+C. W lokalnej weryfikacji potwierdzono odczyt 200, domyślny sukces procesu przy 404, błąd 22 z --fail-with-body oraz poprawny POST z JSON-em.

Parametry zapytania i uwierzytelnienie

Gdy wartość zawiera spacje lub znaki specjalne, użyj kodowania parametrów:

curl --get --data-urlencode 'search=docker compose' \
  --data-urlencode 'per_page=5' \
  --max-time 15 https://trybtechniczny.pl/wp-json/wp/v2/posts

Nie sklejaj ręcznie adresu z niesprawdzonych wartości. Zwrócone pięć rekordów nie oznacza całego zbioru. Przy eksporcie trzeba obsłużyć paginację API.

Sekretów nie wpisuj bezpośrednio do komendy, którą później skopiujesz do zgłoszenia. Historia powłoki, lista procesów i ślad diagnostyczny mogą ujawnić nagłówki. Wybierz mechanizm dostarczania poświadczeń odpowiedni do klienta i środowiska, a dostęp do pliku konfiguracyjnego ogranicz uprawnieniami.

--verbose pomaga zobaczyć negocjację połączenia i nagłówki, ale przed udostępnieniem logu usuń tokeny, ciasteczka i dane użytkowników. Test powinien korzystać z konta o zakresie adekwatnym do operacji.

Timeout, przekierowanie i TLS

--connect-timeout ogranicza etap zestawiania połączenia, obejmujący także DNS i negocjację TLS. --max-time wyznacza limit całej operacji. Długi transfer może potrzebować innego budżetu niż mała odpowiedź JSON.

Opcja -L podąża za przekierowaniami. Najpierw sprawdź ich cel i wymagania API, zwłaszcza przy wysyłaniu danych. Nie dodawaj automatycznie --location-trusted, aby wymusić przekazywanie poświadczeń do kolejnych hostów.

Przy błędzie certyfikatu popraw nazwę hosta, łańcuch certyfikatów albo zaufany magazyn CA. -k wyłącza istotną kontrolę TLS i nie jest naprawą konfiguracji. Jeśli połączenie jest odrzucane jeszcze przed HTTP, przyda się diagnostyka Connection refused.

Nie ponawiaj każdego POST-a bez zastanowienia

Timeout nie dowodzi, że serwer niczego nie wykonał. Mógł zapisać rekord, a odpowiedź zaginęła. Automatyczne powtórzenie może utworzyć duplikat. Zanim włączysz retry dla zapisu, sprawdź obsługę klucza idempotencji lub możliwość odczytania wyniku operacji.

Odpowiedź 429 wymaga odczytania zasad dostawcy, a często także Retry-After. Mechanizm oczekiwania opisuje poradnik o limitach API, a ochronę skutków zapisu artykuł o retry bez duplikatów.

Najczęstsze pytania

Dlaczego cURL nie zgłasza błędu przy 404?

Domyślnie ocenia powodzenie transferu, nie biznesowy sens odpowiedzi. Dodaj --fail-with-body albo jawnie sprawdź kod HTTP.

Jak wysłać JSON bez problemów z cudzysłowami?

Zapisz treść do pliku UTF-8 i użyj --json @payload.json. Plik nadal musi mieć poprawną składnię.

Dlaczego przykład nie działa w PowerShell?

Sprawdź, czy uruchamiasz curl.exe, oraz składnię kontynuacji linii. Przykłady z ukośnikiem na końcu linii są przeznaczone dla Bash.

Czy cURL potwierdzi poprawność całej integracji?

Pomoże sprawdzić konkretne żądanie. Nadal potrzebujesz kontroli schematu, paginacji, uprawnień i skutków operacji.

Źródła

Data publikacji: 03.11.2026.

KP
O AUTORZE

Krystian Proć

Tworzę narzędzia do pracy z danymi, systemy backendowe i automatyzacje. Pracuję z SQL, PHP, TypeScriptem i Dockerem; rozwijam m.in. dragon-island.com. AI pomaga mi przyspieszać pracę, a architekturę, weryfikację i decyzje techniczne biorę na siebie. Na Trybie Technicznym dzielę się doświadczeniami z budowania i utrzymywania własnych projektów.

Dyskusja

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Wymagane pola są oznaczone *