API REST (*Representational State Transfer*) to webowy interfejs, w którym każda dana jest udostępniona jako zasób identyfikowany URL-em (`/clients/123`, `/factures/2026-001`) i manipulowana standardowymi metodami HTTP: `GET` do odczytu, `POST` do tworzenia, `PUT`/`PATCH` do modyfikacji, `DELETE` do usuwania. Formatem wymiany niemal zawsze jest JSON. Skonceptualizowany przez Roya Fieldinga w 2000 roku, REST zmiażdżył wcześniejsze standardy (SOAP, RPC, XML-RPC), bo jest prosty, bezstanowy, natywnie cacheowalny przez HTTP i zrozumiały za pomocą zwykłego `curl` lub karty Network w przeglądarce.
REST stał się de facto standardem udostępniania SaaS, CRM, ERP czy dowolnego oprogramowania biznesowego — Stripe, GitHub, Slack, HubSpot, Salesforce, wszyscy mają API REST. Po stronie klienta każdy język potrafi wykonać żądanie HTTP, więc integracja jest banalna. Po stronie serwera rozdzielenie pozwala kilku zespołom (web, mobile, partnerzy) konsumować te same dane. W złożonych architekturach wewnętrznych z mnóstwem relacji między encjami GraphQL zdobywa udział w rynku — ale REST pozostaje rozsądnym domyślnym wyborem dla 80% przypadków.
Dobre API REST sprowadza się do 4 rzeczy: wersjonowanie (`/v1/`, `/v2/`), by nie psuć istniejących klientów, porządne uwierzytelnianie (OAuth 2.0, JWT, klucze API z zakresami), udokumentowana paginacja/filtrowanie oraz poprawne kody HTTP (200, 201, 400, 401, 403, 404, 422, 500 — nie wszystko jako 200 z ukrytym `error: true`). Do powiadomień o zdarzeniach uzupełniamy REST o webhooki typu push zamiast pollingu. To standardowa architektura nowoczesnego oprogramowania na zamówienie, wdrożonego w chmurze w postaci mikroserwisów lub modularnego monolitu.
API REST: co odróżnia dobre od kiepskiego
- Poprawne metody HTTP: `POST` nie odczytuje, `GET` nie modyfikuje — to podstawa, a często wciąż psute.
- Trafne kody statusu: 401 ≠ 403, 422 ≠ 400 — właściwy kod pozwala klientowi obsłużyć błędy czysto.
- Jawne wersjonowanie od v1: `/api/v1/clients` — inaczej zablokujecie się przy każdej zmianie łamiącej kompatybilność.
- Dokumentacja OpenAPI/Swagger generowana z kodu, nie pisana osobno i nieaktualna po 3 miesiącach.
