Moduł 1 · Fundamenty: HTTP, REST i JSON
Czym jest API i REST: zasoby, adresy i reprezentacje
Po tej lekcji wyjaśnisz, czym jest API i co znaczy, że API jest zgodne ze stylem REST. Rozpoznasz zasób, jego adres i reprezentację, a w ćwiczeniu zaprojektujesz pierwsze adresy dla sklepu internetowego.
API: umowa między dwoma programami
API (Application Programming Interface, interfejs programistyczny aplikacji) to opis tego, jak jeden program może poprosić drugi o dane albo o wykonanie działania. Umowa mówi, pod jaki adres wysłać prośbę, w jakim formacie przekazać dane i czego spodziewać się w odpowiedzi. Program, który prosi, nazywamy klientem, a program, który odpowiada, serwerem.
Przykład z kursu: sklep rowerowy Szprycha z Krakowa sprzedaje części i akcesoria. Ma stronę internetową, aplikację na telefon i kasę w punkcie stacjonarnym. Zamiast trzech osobnych baz produktów wszystkie trzy programy pytają jedno API o to samo: listę produktów, ceny i stan magazynu. Gdy sprzedawca zmieni cenę kasku, nową cenę od razu widać w każdym z tych miejsc.
API spotkasz też poza własną firmą. Narodowy Bank Polski udostępnia kursy walut przez publiczne API, a Ministerstwo Finansów przez API wykazu podatników VAT pozwala sprawdzić status kontrahenta po numerze NIP. Z obu skorzystasz w module 3.
Najczęściej API działa przez protokół HTTP, ten sam, którego używa przeglądarka. Dlatego do pierwszych prób wystarczy terminal i program curl, który wysyła żądania HTTP z wiersza poleceń.
REST: styl, a nie protokół
REST (Representational State Transfer) opisał Roy Fielding w rozprawie doktorskiej z 2000 roku. To styl architektury, czyli zestaw ograniczeń. Nie jest to protokół, biblioteka ani format danych. API, które przestrzega tych ograniczeń, nazywa się potocznie REST API albo RESTful API.
Na podstawie: R. Fielding, rozprawa doktorska, rozdział 5 (2000).
Dwa ograniczenia warto zrozumieć od razu. Bezstanowość oznacza, że serwer nie pamięta poprzedniej rozmowy z klientem. Jeśli aplikacja kasowa chce pobrać drugą stronę listy produktów, musi w żądaniu podać, o którą stronę chodzi, i dołączyć dane logowania. Dzięki temu dowolny z kilku serwerów może obsłużyć dowolne żądanie, co ułatwia rozbudowę. Jednolity interfejs oznacza, że każde API w tym stylu działa podobnie: masz zasoby z adresami i standardowe metody HTTP, więc ucząc się jednego API, uczysz się trochę każdego.
Zasób, adres i reprezentacja
Zasób to wszystko, co ma sens nazwać i udostępnić: produkt, zamówienie, klient, raport. Każdy zasób ma adres URI. W sklepie Szprycha wygląda to tak:
https://api.szprycha.example/produkty kolekcja produktów
https://api.szprycha.example/produkty/5 jeden produkt o id 5
https://api.szprycha.example/zamowienia/42 jedno zamówienieZwróć uwagę, że adresy to rzeczowniki. Nie piszemy /pobierzProdukty ani /usunProdukt?id=5. Co ma się stać, mówi metoda HTTP: GET /produkty/5 pobiera produkt, a DELETE /produkty/5 go usuwa. Metodami zajmiesz się dokładnie w module 2.
Klient nigdy nie dostaje samego zasobu, tylko jego reprezentację, czyli zapis stanu w wybranym formacie. Ten sam kask może mieć reprezentację w JSON dla aplikacji i w HTML dla przeglądarki. Format opisuje nagłówek Content-Type, na przykład application/json. W kursie pracujesz głównie z JSON, bo w tym formacie odpowiadają też oba publiczne API z modułu 3: NBP i wykazu podatników VAT.
{ "id": 5, "nazwa": "Kask miejski M", "kategoria": "akcesoria", "cenaGr": 18900, "stan": 8 }Cena jest zapisana w groszach jako liczba całkowita (18900 gr to 189,00 zł). To świadoma decyzja: liczby zmiennoprzecinkowe w wielu językach dają błędy zaokrągleń, a liczby całkowite groszy dodają się dokładnie.
REST, SOAP, GraphQL: gdzie jest miejsce REST
REST nie jest jedynym sposobem budowania API. SOAP to starszy standard oparty na XML i ścisłych kontraktach WSDL, wciąż spotykany w starszych systemach integracyjnych. GraphQL pozwala klientowi w jednym zapytaniu wskazać dokładnie te pola, których potrzebuje. W tym kursie uczysz się REST, bo opiera się bezpośrednio na HTTP i jego znajomość przydaje się także przy pozostałych podejściach.
Uproszczone porównanie, stan na październik 2026.
Najważniejsze w 3 punktach
- API to umowa, jak programy wymieniają dane; REST to styl architektury z sześcioma ograniczeniami Fieldinga, a nie protokół.
- W REST każdy zasób ma adres będący rzeczownikiem, a działanie wyraża metoda HTTP.
- Klient dostaje reprezentację zasobu, której format opisuje nagłówek
Content-Type, najczęściej JSON.
Źródła
- Roy T. Fielding, Architectural Styles and the Design of Network-based Software Architectures, rozdział 5 „Representational State Transfer” (2000): https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
- RFC 9110, HTTP Semantics (zasoby, reprezentacje, Content-Type), czerwiec 2022: https://www.rfc-editor.org/rfc/rfc9110
- MDN Web Docs, An overview of HTTP, stan na październik 2026: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Overview
- Narodowy Bank Polski, API kursów walut i cen złota, stan na październik 2026: https://api.nbp.pl/