Czym jest API REST?

API (Application Programming Interface) to interfejs programistyczny, który umożliwia komunikację między różnymi aplikacjami lub komponentami systemu. REST natomiast to skrót od Representational State Transfer – stylu architektonicznego, który definiuje zestaw zasad tworzenia usług sieciowych. Połączenie tych dwóch pojęć daje nam REST API, czyli interfejs oparty na zasadach architektury REST, działający za pośrednictwem protokołu HTTP.

Koncepcja REST została opisana po raz pierwszy w 2000 roku przez Roya Fieldinga w jego rozprawie doktorskiej. Od tamtej pory stała się dominującym podejściem w budowaniu usług webowych, wypierając starsze technologie takie jak SOAP (Simple Object Access Protocol). Dziś REST API jest podstawą działania tysięcy aplikacji – od platform społecznościowych, przez systemy płatności, po aplikacje mobilne.

Zasady architektury REST

Aby API można było nazwać RESTful (czyli zgodnym z zasadami REST), musi spełniać kilka podstawowych założeń:

  • Bezstanowość (Statelessness) – każde żądanie wysyłane do serwera powinno zawierać wszystkie informacje niezbędne do jego obsłużenia. Serwer nie przechowuje żadnych danych o stanie sesji klienta między kolejnymi żądaniami.
  • Architektura klient-serwer – klient i serwer są od siebie niezależne. Klient zajmuje się interfejsem użytkownika, serwer – przetwarzaniem danych i logiką biznesową.
  • Jednolity interfejs (Uniform Interface) – komunikacja odbywa się według spójnych, przewidywalnych zasad. Zasoby są identyfikowane przez unikalne adresy URI.
  • Buforowanie (Cacheability) – odpowiedzi serwera mogą być oznaczone jako możliwe lub niemożliwe do zbuforowania, co poprawia wydajność systemu.
  • System warstwowy (Layered System) – architektura może składać się z wielu warstw (np. load balancer, cache, serwer aplikacyjny), a klient nie musi wiedzieć, z którą warstwą się komunikuje.
  • Kod na żądanie (Code on Demand) – opcjonalna zasada pozwalająca serwerowi przesyłać kod wykonywalny do klienta (np. JavaScript).

Jak działa REST API w praktyce?

REST API komunikuje się poprzez protokół HTTP, wykorzystując standardowe metody tego protokołu. Każda operacja na zasobach odbywa się za pomocą odpowiedniej metody HTTP:

  • GET – pobieranie danych (np. lista użytkowników, szczegóły produktu)
  • POST – tworzenie nowego zasobu (np. dodanie nowego użytkownika)
  • PUT – aktualizacja istniejącego zasobu (zamiana całości danych)
  • PATCH – częściowa aktualizacja zasobu (zmiana tylko wybranych pól)
  • DELETE – usunięcie zasobu

Zasoby w REST API są identyfikowane przez URI (Uniform Resource Identifier). Przykładowo, dla aplikacji zarządzającej użytkownikami, adresy mogłyby wyglądać następująco:

  • GET /users – pobierz listę wszystkich użytkowników
  • GET /users/42 – pobierz użytkownika o ID 42
  • POST /users – utwórz nowego użytkownika
  • PUT /users/42 – zaktualizuj dane użytkownika o ID 42
  • DELETE /users/42 – usuń użytkownika o ID 42

Format danych – JSON i XML

REST API może wymieniać dane w różnych formatach, jednak zdecydowanie najpopularniejszym z nich jest JSON (JavaScript Object Notation). Format ten jest czytelny dla człowieka, lekki i łatwy do przetwarzania przez większość języków programowania. Alternatywą jest XML, który jednak jest bardziej rozbudowany i rzadziej spotykany w nowoczesnych API.

Przykładowa odpowiedź serwera w formacie JSON na żądanie GET /users/42 może wyglądać tak:

{
  "id": 42,
  "name": "Jan Kowalski",
  "email": "jan.kowalski@example.com",
  "role": "admin",
  "createdAt": "2025-03-15T10:30:00Z"
}

Dane przesyłane są w ciele (body) żądania lub odpowiedzi HTTP. Nagłówek Content-Type: application/json informuje odbiorcę o formacie przesyłanych danych.

Kody statusu HTTP

Ważnym elementem REST API są kody statusu HTTP, które informują klienta o wyniku wykonanej operacji. Najważniejsze z nich to:

  • 200 OK – żądanie zostało przetworzone pomyślnie
  • 201 Created – zasób został pomyślnie utworzony
  • 204 No Content – żądanie powiodło się, ale nie ma treści do zwrócenia (np. przy DELETE)
  • 400 Bad Request – błędne żądanie, np. brakujące dane w formularzu
  • 401 Unauthorized – brak autoryzacji, klient nie jest zalogowany
  • 403 Forbidden – dostęp zabroniony, mimo poprawnej autoryzacji
  • 404 Not Found – zasób nie istnieje
  • 500 Internal Server Error – błąd po stronie serwera

Poprawne stosowanie kodów statusu to jedna z cech dobrze zaprojektowanego REST API. Dzięki nim klient może łatwo zinterpretować wynik operacji bez konieczności analizowania treści odpowiedzi.

Autoryzacja i bezpieczeństwo

Bezpieczeństwo REST API to niezwykle ważny aspekt każdej aplikacji. Ponieważ REST API jest bezstanowe, tradycyjne mechanizmy sesji nie mają tu zastosowania. Zamiast tego stosuje się kilka popularnych metod autoryzacji:

  • API Key – unikalny klucz przypisany do klienta, przesyłany w nagłówku lub parametrze zapytania. Prosty w implementacji, ale mniej bezpieczny.
  • Bearer Token / JWT – JSON Web Token to podpisany token zawierający informacje o użytkowniku. Jest przesyłany w nagłówku Authorization: Bearer <token>. Bardzo popularne rozwiązanie w nowoczesnych aplikacjach.
  • OAuth 2.0 – standard autoryzacji stosowany przez duże platformy (Google, Facebook, GitHub). Pozwala na dostęp do zasobów użytkownika bez ujawniania jego hasła.
  • Basic Auth – przesyłanie loginu i hasła w nagłówku żądania (zakodowanych w Base64). Stosowane tylko w połączeniu z HTTPS.

Niezależnie od wybranej metody autoryzacji, REST API zawsze powinno działać przez szyfrowane połączenie HTTPS. Warto też stosować mechanizmy rate limiting (ograniczania liczby żądań), walidacji danych wejściowych oraz odpowiedniego logowania zdarzeń.

Dokumentacja API – Swagger i OpenAPI

Dobra dokumentacja to fundament każdego API przeznaczonego dla innych deweloperów. Najpopularniejszym standardem opisywania REST API jest OpenAPI Specification (dawniej Swagger). Pozwala ona na tworzenie szczegółowych opisów endpointów, parametrów, schematów danych i przykładów odpowiedzi – zarówno w formacie YAML, jak i JSON.

Na podstawie takiej specyfikacji można automatycznie generować interaktywną dokumentację (np. za pomocą Swagger UI), którą deweloperzy mogą przeglądać w przeglądarce i natychmiast testować żądania. Narzędzia takie jak Postman czy Insomnia są powszechnie używane do ręcznego testowania i eksploracji API podczas developmentu.

REST API a inne podejścia – GraphQL i gRPC

REST API nie jest jedynym dostępnym rozwiązaniem. W ostatnich latach popularność zyskały dwa alternatywne podejścia:

  • GraphQL – opracowany przez Facebooka język zapytań, który pozwala klientowi precyzyjnie określić, jakie dane chce pobrać. Eliminuje problem over-fetchingu (pobierania zbyt wielu danych) i under-fetchingu (konieczności wysyłania wielu żądań). Świetnie sprawdza się w złożonych aplikacjach z wieloma powiązanymi zasobami.
  • gRPC – framework od Google oparty na protokole HTTP/2 i buforach protokołu (Protocol Buffers). Oferuje bardzo wysoką wydajność i jest chętnie stosowany w komunikacji między mikroserwisami.

Każde z tych podejść ma swoje mocne strony. REST API wyróżnia się prostotą, powszechnością i doskonałą obsługą przez przeglądarki oraz narzędzia deweloperskie. Dla większości projektów webowych i mobilnych nadal pozostaje najlepszym wyborem.

Praktyczny przykład – wywołanie REST API w JavaScript

Zobaczmy, jak wygląda wywołanie REST API w praktyce, korzystając z wbudowanego w przeglądarki interfejsu fetch:

// Pobieranie danych użytkownika
fetch('https://api.example.com/users/42', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  if (!response.ok) {
    throw new Error('Błąd: ' + response.status);
  }
  return response.json();
})
.then(data => console.log(data))
.catch(error => console.error(error));

W powyższym przykładzie wysyłamy żądanie GET do endpointu /users/42, dołączając token JWT w nagłówku autoryzacyjnym. Po otrzymaniu odpowiedzi parsujemy ją jako JSON i wyświetlamy w konsoli. Podobne wywołania można realizować w Pythonie (biblioteka requests), PHP, Javie, czy praktycznie każdym innym języku programowania.

Podsumowanie

REST API to niezwykle potężne i wszechstronne narzędzie, które stało się fundamentem współczesnego internetu. Jego prostota, skalowalność i niezależność od platformy sprawiają, że jest doskonałym wyborem zarówno dla małych startupów, jak i dużych korporacji. Znajomość zasad REST API jest dziś jedną z kluczowych kompetencji każdego programisty webowego – niezależnie od tego, czy pracuje po stronie frontendu, backendu, czy zajmuje się integracją systemów.

Jeśli dopiero zaczynasz swoją przygodę z REST API, polecamy zacząć od eksperymentowania z publicznymi API (np. JSONPlaceholder) i narzędziami takimi jak Postman. Praktyczne ćwiczenia to najszybsza droga do zrozumienia, jak te technologie działają w realnych projektach.