Czego szukasz?

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

← Wszystkie artykuły

REST API: co to jest i jak zacząć z niego korzystać

Uproszczone okno przeglądarki i symbol danych połączone przeciwnie skierowanymi strzałkami.

Gdy chcesz pobrać dane z innej aplikacji, nie musisz automatycznie otwierać jej strony i klikać przycisków. Często możesz wysłać żądanie do API i otrzymać odpowiedź, którą odczyta Twój skrypt. REST API pozwala pracować z zasobami przez uzgodniony interfejs, zwykle oparty na HTTP.

Pokażę to na publicznym API GitHuba. Pobierzemy opis repozytorium, rozdzielimy nagłówki od danych i sprawdzimy błąd 404. Przykłady odczytują publiczne informacje i nie wymagają konta ani tokenu.

Co oznacza REST API

API określa, jak programy mogą korzystać z udostępnionych funkcji lub danych. REST jest stylem architektury opisującym między innymi podział klient-serwer, bezstanową komunikację, jednolity interfejs oraz zasady buforowania.

W praktycznym API spotkasz zasoby, takie jak użytkownik, wpis lub zamówienie. Zasób ma adres, a klient wymienia z serwerem jego reprezentację. Często jest nią JSON, ale REST nie wymaga wyłącznie tego formatu.

Nie każde API zwracające JSON spełnia wszystkie ograniczenia REST. Wiele usług używa tej nazwy w szerszym znaczeniu. Przy integracji ważniejszy od etykiety jest konkretny kontrakt: dostępne operacje, format danych, uwierzytelnianie i zachowanie przy błędach.

Bezstanowość też łatwo źle zrozumieć. Serwer może przechowywać dane w bazie. Chodzi o to, aby pojedyncze żądanie zawierało informacje potrzebne do jego obsługi, zamiast wymagać od serwera pamiętania poprzednich kroków rozmowy klienta.

Z czego składa się żądanie

Spójrz na adres:

https://api.github.com/repos/octocat/Hello-World

https://api.github.com wskazuje usługę. Ścieżka wybiera konkretne repozytorium. Do tego dochodzą metoda HTTP, nagłówki, a przy części operacji również treść żądania.

Element Przykład Rola
Metoda GET Określa rodzaj operacji
Ścieżka /repos/octocat/Hello-World Wybiera zasób
Parametry zapytania ?per_page=10 Doprecyzowują żądanie
Nagłówek Accept: application/vnd.github+json Informuje o oczekiwanej reprezentacji
Treść Dokument JSON Przekazuje dane, jeśli operacja ich wymaga

Adres endpointu nie jest tym samym co adres strony dla człowieka. Repozytorium oglądasz na github.com, ale programowe dane pobierasz z api.github.com. Kopiowanie HTML strony zamiast użycia jej API zwykle utrudnia integrację i uzależnia ją od wyglądu interfejsu.

Pierwsze żądanie z cURL

Potrzebujesz programu curl. Sprawdź go poleceniem curl --version. Poniższe przykłady używają składni Bash. W PowerShell wywołuj curl.exe, jeśli nazwa curl wskazuje inne polecenie; wielowierszowe przykłady najprościej skleić w jedną linię.

curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 30 \
  -H 'Accept: application/vnd.github+json' \
  -H 'User-Agent: tryb-techniczny-example' \
  -D headers.txt \
  -o repo.json \
  https://api.github.com/repos/octocat/Hello-World

Odpowiedź trafia do repo.json, a nagłówki do headers.txt. Rozdzielenie tych plików ułatwia pracę: kod statusu i limity odczytasz z nagłówków, natomiast dane repozytorium pozostają poprawnym JSON-em.

--connect-timeout ogranicza czas zestawiania połączenia, a --max-time czas całej operacji. Dzięki --fail-with-body odpowiedź HTTP z błędem powoduje niezerowy kod zakończenia, ale jej treść nadal jest dostępna. Opcja wymaga cURL 7.76.0 lub nowszego.

Nie zakładaj, że samo zakończenie programu oznacza powodzenie operacji. Bez odpowiednich opcji cURL może poprawnie pobrać odpowiedź HTTP 404 i zakończyć pracę kodem zero.

Jak odczytać JSON

Otwórz plik lub użyj Pythona 3, aby wyświetlić wybrane pola:

python3 -c 'import json; d=json.load(open("repo.json", encoding="utf-8")); print(d["full_name"]); print(d["html_url"])'

Ten przykład pokazuje nazwę repozytorium oraz jego stronę. Liczba gwiazdek czy data aktualizacji mogą się zmieniać, dlatego nie traktuj przykładowych wartości jako stałych.

JSON rozróżnia tekst, liczby, wartości logiczne, null, obiekty i tablice. Tekst "false" nie jest tym samym co wartość logiczna false. Podobnie pusty tekst nie musi oznaczać braku wartości. Te różnice mają znaczenie, gdy przekazujesz dane do kolejnego systemu.

Do czytelnego formatowania neutralnych danych przyda się formatter JSON. W kodzie korzystaj z parsera, zamiast wycinać pola wyrażeniem regularnym. Przy większej integracji sprawdź też, co ma się stać, jeśli pole jest nieobecne lub ma wartość null.

GET, POST, PUT, PATCH i DELETE

Metoda jest częścią znaczenia żądania. Sama nazwa endpointu nie wystarcza do ustalenia, czy operacja tylko czyta, czy zmienia dane.

Metoda Typowe zastosowanie O czym pamiętać
GET Pobranie reprezentacji Nie powinna żądać zmiany stanu zasobu
POST Przetworzenie danych, często utworzenie zasobu Powtórzenie może utworzyć kolejny obiekt
PUT Utworzenie lub zastąpienie stanu pod wskazanym adresem Nie zakładaj, że pominięte pola pozostaną bez zmian
PATCH Częściowa zmiana Format i semantykę poprawki określa API
DELETE Usunięcie powiązania zasobu z adresem Kolejna próba może zwrócić inny status

Idempotencja oznacza, że wielokrotne wykonanie identycznego żądania ma taki sam zamierzony skutek jak jedno wykonanie. Nie wymaga identycznej odpowiedzi. Dlatego DELETE może najpierw zwrócić sukces, a potem 404, bez naruszenia tej właściwości.

Nie zakładaj natomiast, że dowolny PATCH lub POST można bezpiecznie ponowić. Jeśli serwer utworzył zamówienie, ale odpowiedź zginęła w sieci, ponowienie POST może utworzyć duplikat. Korzystaj z mechanizmu idempotencji dostawcy, jeśli go udostępnia, lub sprawdzaj wynik operacji przed ponowieniem.

Status odpowiedzi to pierwsza wskazówka

Status Co zwykle oznacza Następny krok
200 Żądanie zakończone powodzeniem Odczytaj reprezentację
201 Utworzono zasób Sprawdź identyfikator lub Location
204 Powodzenie bez treści Nie próbuj parsować pustego JSON-a
400 Nieprawidłowe żądanie Porównaj dane z kontraktem API
401 Brak poprawnego uwierzytelnienia Sprawdź token i sposób jego przekazania
403 Serwer odmawia wykonania Sprawdź uprawnienia, politykę i opis błędu
404 Nie znaleziono zasobu Sprawdź adres; API może też ukrywać brak dostępu
429 Ograniczenie liczby żądań Uwzględnij zalecany czas oczekiwania
5xx Błąd po stronie serwera lub bramy Zapisz kontekst i zastosuj ograniczone ponowienia

Sprawdź kontrolowany błąd dla nieistniejącego endpointu:

curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 30 \
  -H 'User-Agent: tryb-techniczny-example' \
  -o error.json -w '%{http_code}\n' \
  https://api.github.com/tryb-techniczny-nieistniejacy-endpoint

Treść odpowiedzi może wyjaśnić problem dokładniej niż sam status. Nie publikuj jednak całych logów żądań, jeśli zawierają tokeny lub dane klientów. Warto zachować czas, metodę, ścieżkę, status i identyfikator żądania zwracany przez dostawcę.

Problemy transportowe są osobną kategorią: przy braku połączenia możesz w ogóle nie otrzymać statusu HTTP. Dla własnego serwera sprawdź diagnostykę Connection refused, a przy reverse proxy także poradnik o błędzie 502.

Token nie jest zwykłym parametrem konfiguracyjnym

Publiczny przykład działa bez tokenu, ale prywatne zasoby zwykle wymagają uwierzytelnienia. Sposób przekazania poświadczeń określa dostawca. Często jest to nagłówek Authorization, lecz nie należy przenosić składni z jednej usługi do drugiej bez sprawdzenia dokumentacji.

Przygotuj token o najmniejszych potrzebnych uprawnieniach. Trzymaj go poza repozytorium i nie umieszczaj w adresie URL, jeśli API tego nie wymaga. Adresy łatwo trafiają do historii, logów serwera i narzędzi analitycznych.

Zmienne środowiskowe są wygodne, ale nie stanowią automatycznie bezpiecznego sejfu. W procesie wdrożenia ustal, kto może je odczytać, jak wymienisz token i co zrobisz po wycieku. W poradniku o wdrażaniu przez GitHub Actions podobny problem dotyczy sekretów używanych przez automatyzację.

Paginacja, limity i zmieniające się dane

Endpoint zwracający listę często oddaje tylko pierwszą stronę. Poprawny JSON z dwudziestoma rekordami nie dowodzi, że pobrałeś cały zbiór. Czytaj dokumentację parametrów oraz informacje o następnej stronie.

W API GitHuba paginacja może wykorzystywać nagłówek Link. Sprawdzaj relację next, zamiast konstruować dowolnie duże numery stron. Inne API używają kursora w treści odpowiedzi. Kursor traktuj jak nieprzezroczysty identyfikator, bez zgadywania jego budowy.

Limity też nie muszą być identyczne dla wszystkich endpointów i metod uwierzytelnienia. Odczytuj nagłówki oraz dokumentację usługi. Zamiast odpalać zapytanie co sekundę, dopasuj częstotliwość do rzeczywistej potrzeby. Część zmian można odbierać przez webhook, bez ciągłego sprawdzania całej listy.

Do prostego harmonogramu pasuje cron w Linuxie. Przy przepływie obejmującym kilka usług wygodniejsze może być n8n. W obu przypadkach trzeba obsłużyć timeout, błędną odpowiedź i częściowe wykonanie zadania.

Najczęstsze pytania

Czy REST API zawsze zwraca JSON?

Nie. JSON jest popularną reprezentacją, ale REST nie ogranicza interfejsu do jednego formatu. Sprawdź nagłówek Content-Type oraz dokumentację endpointu.

Dlaczego w przeglądarce działa, a w skrypcie nie?

Przeglądarka może mieć sesję, ciasteczka lub dodatkowe nagłówki. Skrypt musi użyć obsługiwanego mechanizmu uwierzytelnienia. Nie kopiuj bezmyślnie całej sesji do automatyzacji.

Czy CORS blokuje cURL?

Nie działa w cURL jak mechanizm kontroli stosowany przez przeglądarkę. CORS dotyczy odczytu odpowiedzi przez kod strony z innego originu. Serwer nadal może niezależnie wymagać tokenu i odmawiać dostępu.

Jak odróżnić API od webhooka?

Przy typowym wywołaniu API to Twój program inicjuje żądanie. Webhook pozwala innej usłudze wywołać przygotowany przez Ciebie endpoint po wystąpieniu zdarzenia. Oba mechanizmy mogą korzystać z HTTP i JSON-a.

Od czego zacząć własną integrację?

Najpierw odczytaj jeden publiczny zasób, sprawdź status i sparsuj odpowiedź. Następnie dodaj uwierzytelnianie, paginację oraz obsługę błędów potrzebnych w konkretnym zadaniu. Operacje zmieniające dane testuj w środowisku przeznaczonym do prób.

Źródła

Data publikacji: 20.10.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 *