API od zera: czym są API, JSON i HTTP? Przykłady i poradnik

• API określa dostępne operacje i zasady korzystania z nich.
• HTTP pozwala klientowi wysłać żądanie, a serwerowi udzielić odpowiedzi.
• JSON opisuje strukturę danych, na przykład wpis z tytułem i identyfikatorem.
• Przy pracy z API sprawdzaj metodę, adres, nagłówki, dane oraz kod odpowiedzi.
• Zacznij od pobierania danych z usługi szkoleniowej; sekrety zachowaj dla siebie.

API rozwija się jako Application Programming Interface, czyli interfejs programowania aplikacji. Interfejs oznacza tutaj zestaw możliwości i reguł dostępnych dla innego programu. Definicja API w MDN porównuje go do umowy między aplikacją udostępniającą funkcje a jej odbiorcą.

Wyobraź sobie aplikację do planowania wyjazdu. Zamiast samodzielnie gromadzić prognozy, mogłaby wysłać do API pogodowego nazwę miasta i odebrać temperaturę. Dokumentacja takiej usługi musiałaby wyjaśniać, jak wskazać miasto, jakie dane wracają i jakie obowiązują ograniczenia.

API nie musi oznaczać usługi internetowej. Może także udostępniać funkcje przeglądarki lub oprogramowania działającego na komputerze, co pokazują przykłady API w MDN. Tutaj skupimy się na komunikacji z usługą przez HTTP.

Klient, serwer i zasób

Klient to program wysyłający żądanie, na przykład narzędzie w terminalu. Serwer przyjmuje żądanie i przygotowuje odpowiedź. Zasób to rzecz, do której się odwołujesz, na przykład konkretny wpis albo kolekcja wpisów.

W modelu komunikacji HTTP klient inicjuje żądanie, a serwer odpowiada. Poniższy diagram przedstawia nasze przyszłe ćwiczenie:

sequenceDiagram
    participant K as Klient
    participant S as Serwer API
    K->>S: GET /posts/1
    S-->>K: Status i dane JSON
    Note over K: Odczyt pól wpisu

REST, skrót od Representational State Transfer, oznacza styl projektowania systemów oparty na określonych zasadach. Nie jest formatem danych. MDN wyjaśnia pojęcie REST i zaznacza, że usługi HTTP bywają nazywane REST API, choć nie zawsze spełniają wszystkie jego wymagania.

HTTP, czyli Hypertext Transfer Protocol, jest protokołem: zbiorem zasad komunikacji. Można nim przesyłać różne zasoby, także dokumenty i obrazy, jak opisuje przewodnik po HTTP. Samo użycie HTTP nie przesądza więc, że odpowiedź będzie JSON.

HTTPS to komunikacja HTTP zabezpieczona szyfrowaniem. Przy korzystaniu z prawdziwych usług zalecam wybieranie adresów zaczynających się od https://; zalecenia OWASP dotyczące HTTPS wskazują ochronę danych uwierzytelniających podczas transmisji.

Adres i parametry

URL to adres zasobu. Endpoint, czyli punkt dostępu API, wskazuje miejsce wykonywania określonej operacji. Przykładowy adres z dokumentacji JSONPlaceholder wygląda tak:

https://jsonplaceholder.typicode.com/posts?userId=1

Możesz przeczytać go w trzech częściach:

• https://jsonplaceholder.typicode.com wskazuje usługę;
• /posts jest ścieżką do kolekcji wpisów;
• ?userId=1 zawiera parametr zapytania, czyli dodatkową informację dla serwera.

W tym API parametr wybiera wpisy użytkownika wskazanego przez userId. Nie przenoś tej nazwy automatycznie do innej usługi. Zalecam kopiowanie nazw parametrów z jej dokumentacji, a następnie zmianę wyłącznie wartości potrzebnych w projekcie.

Metoda, nagłówki i treść

Metoda HTTP określa rodzaj operacji. Nagłówki przekazują dodatkowe informacje o komunikacie, a jego treść, nazywana też body, zawiera przesyłane dane. Ich miejsce w żądaniu i odpowiedzi pokazuje dokumentacja komunikatów HTTP.

Dwa nagłówki łatwo pomylić. Accept wskazuje formaty, które klient potrafi odebrać, natomiast Content-Type opisuje format przesyłanej treści. Wartość application/json oznacza JSON, zgodnie z rejestracją tego typu w standardzie JSON.

Przy pobieraniu wpisu możesz zadeklarować Accept: application/json. Przy wysyłaniu danych JSON ustawiasz Content-Type: application/json. Żaden z tych napisów sam nie poprawi błędnie zapisanych danych.

JSON rozwija się jako JavaScript Object Notation. Jest tekstowym formatem niezależnym od języka programowania. Standard JSON opisuje tekst, liczby, wartości logiczne, null, obiekty i tablice.

To własny przykład danych użytkownika, a nie odpowiedź usługi z ćwiczenia:

{
  "id": 7,
  "imie": "Łucja",
  "aktywny": true,
  "telefon": null,
  "umiejetnosci": ["HTTP", "JSON"]
}

Obiekt, zapisany w {}, grupuje pary klucz i wartość. Klucz imie ma tutaj wartość tekstową Łucja. Tablica, zapisana w [], jest uporządkowaną listą; w przykładzie zawiera dwie umiejętności.

true oznacza prawdę, false fałsz, a null specjalną wartość pustą. Nie traktuj null automatycznie jako zera ani pustego tekstu. W tym przykładzie wybraliśmy ją do oznaczenia braku telefonu.

Zasady poprawnego zapisu

Z gramatyki JSON wynikają następujące zasady:

• klucze i tekst umieszczasz w podwójnych cudzysłowach;
• elementy oddzielasz przecinkami, bez przecinka po ostatnim;
• wartości true, false i null zapisujesz małymi literami;
• w liczbie dziesiętnej używasz kropki;
• nie dodajesz komentarzy do danych.

Parser to narzędzie odczytujące zapis danych. ECMA-404 opisuje składnię JSON, bez ustalania znaczenia danych. Dlatego zalecam osobne porównanie wymaganych pól i ich typów z dokumentacją API, zanim wyślesz dane.

Najczęściej spotykane operacje zestawiono poniżej według dokumentacji metod HTTP. Przykładowe zastosowania są ilustracją, a szczegóły operacji zawsze sprawdzaj w dokumentacji wybranego API.

Reprezentacja to postać danych opisujących zasób, na przykład dokument JSON. Dla początkującego praktyczne pytanie brzmi: czy chcesz coś odczytać, dodać, zmienić czy usunąć? Następnie sprawdź, jak usługa realizuje tę potrzebę.

Skorzystamy z JSONPlaceholder, usługi udostępniającej fikcyjne dane do ćwiczeń, bez rejestracji i klucza API. curl to narzędzie do przesyłania danych pod wskazany adres. Terminal pozwala uruchamiać programy za pomocą wpisywanych poleceń.

Wymagania

Przygotuj komputer z Ubuntu 24.04 LTS, połączenie z internetem oraz uprawnienia administratora do instalacji. Pakiety curl i python3 są dostępne dla tego wydania. Python, język programowania, posłuży tutaj wyłącznie do czytelnego wyświetlania JSON.

Uruchamiaj kolejne polecenia w tym samym terminalu, z folderu ćwiczenia api-start. Nie potrzebujesz konta w usłudze ani własnego kodu aplikacji.

1. Przygotuj narzędzia

Najpierw zainstaluj narzędzia zgodnie ze sposobem zarządzania pakietami Ubuntu:

sudo apt update
sudo apt install curl python3
mkdir -p api-start
cd api-start

sudo: unable to send audit message: Operation not permitted

WARNING: apt does not have a stable CLI interface. Use with caution in scripts.

Hit:1 http://archive.ubuntu.com/ubuntu noble InRelease
Get:2 http://archive.ubuntu.com/ubuntu noble-updates InRelease [126 kB]
Hit:3 http://archive.ubuntu.com/ubuntu noble-backports InRelease
Hit:4 https://cli.github.com/packages stable InRelease
Hit:5 https://download.docker.com/linux/ubuntu noble InRelease
Hit:6 https://deb.nodesource.com/node_24.x nodistro InRelease
…
0 upgraded, 0 newly installed, 0 to remove and 2 not upgraded.

sudo uruchamia polecenie z uprawnieniami administratora. apt update odświeża lokalny indeks dostępnych pakietów, a apt install instaluje wskazane narzędzia i potrzebne zależności. Sprawdź proponowane zmiany przed zatwierdzeniem instalacji.

mkdir tworzy folder, a cd przechodzi do niego. Po zakończeniu instalacji terminal powinien wrócić do znaku zachęty, czyli miejsca wpisywania kolejnego polecenia. Jeśli pakiety są już zainstalowane, komunikat może to wskazać.

2. Pobierz wpis i obejrzyj odpowiedź

Uruchom polecenie:

curl -sS -i --max-time 20 'https://jsonplaceholder.typicode.com/posts/1'

HTTP/2 200 
date: Tue, 06 Oct 2026 09:27:06 GMT
content-type: application/json; charset=utf-8
content-length: 292
access-control-allow-credentials: true
cache-control: max-age=43200
etag: W/"124-yiKdLzqO5gfBrJFrcdJ8Yq0LGnU"
expires: -1
pragma: no-cache
vary: Origin, Accept-Encoding
…
}

Według dokumentacji curl -sS ukrywa pasek postępu, zachowując komunikaty błędów, -i dołącza nagłówki odpowiedzi, a --max-time 20 ogranicza czas transferu do 20 sekund. W tym wywołaniu curl używa metody GET.

Szukaj statusu odpowiedzi, nagłówków i danych wpisu. Odpowiedź endpointu /posts/1 zawiera pola userId, id, title i body, z identyfikatorem wpisu równym 1. Pole body w tym JSON jest treścią wpisu; nie należy mylić jego nazwy z treścią całego komunikatu HTTP.

3. Wyświetl sam JSON czytelniej

Do formatowania użyj json.tool z biblioteki standardowej Pythona:

curl -sS --max-time 20 'https://jsonplaceholder.typicode.com/posts/1' | python3 -m json.tool

{
    "userId": 1,
    "id": 1,
    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
    "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}

Znak |, używany w potoku powłoki Bash, przekazuje wynik pierwszego programu do drugiego. Powłoka to program interpretujący polecenia terminala. Zobaczysz dane z wcięciami. Celowo pomijamy -i, ponieważ nagłówki HTTP nie są częścią dokumentu JSON.

4. Odfiltruj listę

Zastosuj parametr z dokumentacji usługi:

curl -sS --max-time 20 'https://jsonplaceholder.typicode.com/posts?userId=1' | python3 -m json.tool

[
    {
        "userId": 1,
        "id": 1,
        "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
        "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
    },
    {
        "userId": 1,
        "id": 2,
…
]

Wynik powinien być tablicą wpisów użytkownika 1, co pokazuje odpowiedź filtrowanego endpointu. Porównaj początek wyniku: pojedynczy wpis był obiektem {}, natomiast lista jest tablicą [].

5. Wyślij dane

Poniższe polecenie wysyła przykładowy wpis:

curl -sS -i --max-time 20 \
  -H 'Content-Type: application/json' \
  --data '{"title":"Pierwszy wpis","body":"Uczę się API","userId":1}' \
  'https://jsonplaceholder.typicode.com/posts'

HTTP/2 201 
date: Tue, 06 Oct 2026 09:27:06 GMT
content-type: application/json; charset=utf-8
content-length: 86
location: https://jsonplaceholder.typicode.com/posts/101
access-control-allow-credentials: true
access-control-expose-headers: Location
cache-control: no-cache
etag: W/"56-wv/8aOM9dX9Kd1V+8/Zkfacrn44"
expires: -1
…
}

Opcja --data w curl wysyła dane metodą POST, a -H ustawia nagłówek. Ukośniki odwrotne na końcach wierszy pozwalają zapisać jedno polecenie w kilku liniach.

Oczekuj przesłanych pól oraz id: 101, tak jak w przykładzie tworzenia zasobu JSONPlaceholder. Usługa symuluje utworzenie wpisu, bez rzeczywistego zapisu na serwerze. Nie oczekuj więc trwałego wpisu dostępnego później pod nowym adresem.

Kod statusu HTTP opisuje wynik obsługi żądania. Dokumentacja statusów wyróżnia między innymi sukcesy 2xx, błędy klienta 4xx i błędy serwera 5xx; x zastępuje tutaj dowolną cyfrę.

Znaczenia poniższych kodów pochodzą z tej dokumentacji, a wskazówki są proponowaną kolejnością diagnozy:

• 200 OK: żądanie zakończyło się sukcesem. Sprawdź otrzymane dane.
• 201 Created: utworzono zasób. W usłudze szkoleniowej uwzględnij opis jej symulacji.
• 204 No Content: sukces bez treści odpowiedzi. Nie próbuj wtedy odczytywać JSON.
• 400 Bad Request: serwer odrzuca żądanie jako błędne. Zalecam sprawdzenie składni i wymaganych pól.
• 401 Unauthorized: potrzebne jest uwierzytelnienie, czyli potwierdzenie tożsamości klienta. Sprawdź wymagane dane dostępu.
• 403 Forbidden: serwer odmawia dostępu. Sprawdź uprawnienia do operacji.
• 404 Not Found: zasobu nie znaleziono. Porównaj ścieżkę i identyfikator z dokumentacją.
• 429 Too Many Requests: zbyt wiele żądań w danym czasie. Sprawdź zasady limitowania usługi.
• 500 Internal Server Error: nieoczekiwany problem serwera. Zalecam zachowanie opisu błędu bez sekretów.

Błąd JSON lub brak odpowiedzi

Jeśli json.tool zgłasza błąd, wróć do kroku z curl -i. Zalecam najpierw sprawdzenie statusu i rodzaju treści: mogła przyjść strona błędu zamiast danych. Przy błędzie własnego JSON przejrzyj cudzysłowy, przecinki i nazwy wartości logicznych.

Jeśli terminal pokazuje curl: command not found, wróć do instalacji curl. Gdy transfer nie mieści się w ustawionym limicie czasu, sprawdź połączenie i spróbuj ponownie pobrać dane. Zalecam zaczynanie diagnozy od pojedynczego żądania, zanim uruchomisz całą automatyzację.

Działa w terminalu, ale przeglądarka zgłasza CORS

CORS, czyli Cross-Origin Resource Sharing, to mechanizm określający, z jakich źródeł przeglądarka może udostępniać zasoby kodowi strony. Źródło obejmuje schemat adresu (protokół komunikacji), domenę (nazwę serwera) i port (numer, na którym serwer nasłuchuje): w przykładowym adresie https://example.com:8080 są to odpowiednio https, example.com i 8080, zgodnie z opisem składników źródła w MDN. Dokumentacja CORS wyjaśnia rolę nagłówków ustawianych przez serwer.

Zalecam sprawdzenie, czy usługa zezwala na źródło twojej strony. Jeśli zarządzasz serwerem, popraw jego konfigurację; w przeciwnym razie poszukaj w dokumentacji zalecanego sposobu integracji. Wyłączenie zabezpieczeń przeglądarki nie jest dobrym rozwiązaniem dla użytkowników projektu.

Klucz API to wartość używana przez usługę do rozpoznawania wywołującej aplikacji. Token dostępu jest poświadczeniem umożliwiającym dostęp do chronionych zasobów. Sposób jego otrzymania i użycia ustala konkretna usługa.

Jednym ze sposobów przekazania tokenu jest nagłówek opisany w standardzie Bearer:

Authorization: Bearer TWOJ_TOKEN

To wzór nagłówka, nie działający sekret. Posiadacz tokenu Bearer może z niego korzystać, dlatego standard nakazuje chronić tokeny przed ujawnieniem. Zalecam przechowywanie prywatnych sekretów poza publicznym kodem, zrzutami ekranu i rozmowami z narzędziami AI.

Nie umieszczaj hasła ani prywatnego klucza w adresie żądania. OWASP zaleca unikanie poświadczeń w URL, ponieważ mogą trafić do logów serwera. Log to zapis zdarzeń wykonywanych przez system.

Co sprawdzić przed automatyzacją?

Polecam następującą kolejność:

1. Znajdź adres usługi, metodę i przykład poprawnego żądania.
2. Sprawdź wymagane nagłówki, poświadczenia oraz format odpowiedzi.
3. Przeczytaj zasady limitów, kosztów i paginacji, czyli dzielenia wyników na strony.
4. Ustal, czy operacja zapisuje lub usuwa dane, i przygotuj dane testowe.
5. Dopiero po poprawnym pojedynczym wywołaniu dołącz obsługę błędów do programu.

Przy zapisie zalecam sprawdzanie wyniku przed ponowieniem żądania. Metoda POST nie gwarantuje idempotencji, czyli takiego samego skutku wielokrotnego wykonania jak jednego wykonania, co wskazuje zestawienie właściwości metod HTTP. Nie zakładaj więc, że ponowienie tworzenia wpisu nie doda kolejnego.

Czy API to to samo co JSON?

API określa sposób korzystania z funkcji programu, a JSON zapis danych. Możesz odbierać JSON przez API, ale samo skopiowanie dokumentu JSON nie udostępnia operacji do wykonania. W ćwiczeniu operacją było pobranie wpisu, a JSON zawierał jego pola.

Czy do korzystania z API trzeba umieć programować?

Pierwsze żądanie możesz wysłać narzędziem takim jak curl, bez pisania aplikacji. Polecam najpierw zrozumieć odpowiedź, a następnie użyć języka programowania do jej przetwarzania. To dobry moment, by połączyć pobieranie danych z konkretnym zadaniem, na przykład własnym raportem.

Czy każde API wymaga klucza?

Zasady dostępu określa usługa. Używany tutaj JSONPlaceholder nie wymaga klucza API. Przy innym API zalecam sprawdzenie sekcji o uwierzytelnianiu jeszcze przed kopiowaniem pierwszego przykładu.

Czym różni się HTTP od HTTPS?

HTTPS zabezpiecza komunikację HTTP podczas przesyłania danych. Przy tokenach Bearer standard wymaga HTTPS lub równoważnego zabezpieczenia transmisji. Samo HTTPS nie zastępuje jednak zasad przechowywania sekretów.

Polecam teraz zamienić ręczne pobieranie danych w mały program: odczytaj wpis i wyświetl wyłącznie jego tytuł. Zachowaj ten sam endpoint i dane szkoleniowe, żeby skupić się na przetwarzaniu odpowiedzi.