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
- Opcje programu curl, curl project.
- Odpowiedzi HTTP, everything curl.
- Wysyłanie JSON, everything curl.
- Limity czasu, everything curl.
- Weryfikacja certyfikatów, everything curl.
Data publikacji: 03.11.2026.

Dyskusja