Definicja #
API design (projektowanie API) to dziedzina inżynierii oprogramowania skupiona na tworzeniu interfejsów, które są intuicyjne, spójne, bezpieczne i łatwe w utrzymaniu. Dobrze zaprojektowane API jest produktem — musi być zrozumiałe dla konsumentów bez czytania całego kodu źródłowego.
Kluczowe zasady projektowania REST API:
- Nazewnictwo zasobów — rzeczowniki w liczbie mnogiej:
/users,/orders,/products/{id}; nie czasowniki (/getUser) - Metody HTTP jako operacje — GET (odczyt), POST (tworzenie), PUT/PATCH (aktualizacja), DELETE (usuwanie)
- Spójne kody statusu HTTP — 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable Entity, 500 Internal Server Error
- Wersjonowanie —
/api/v1/w ścieżce (najpopularniejsze), nagłówekAccept: application/vnd.api.v1+json, lub parametr query - Paginacja — offset-based (
?page=2&limit=20), cursor-based (dla dużych zbiorów) - Obsługa błędów — spójna struktura błędów:
{ "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [...] } } - HATEOAS — Hypermedia As The Engine Of Application State; linki nawigacyjne w odpowiedzi (REST Level 3)
Poza REST popularne podejścia to GraphQL (klient steruje kształtem danych) i gRPC (wydajne API dla mikroserwisów, kontrakt w Protobuf).
Standard dokumentacji: OpenAPI 3.x (Swagger) — maszyna-czytelny opis API w YAML/JSON, generujący interaktywną dokumentację.
Zastosowania #
API design stosuje się do:
- Projektowania REST API dla aplikacji webowych i mobilnych — definiowanie endpointów, struktur JSON i zasad przed implementacją
- Tworzenia publicznych API dla partnerów i developerów zewnętrznych — czytelne, stabilne API jako produkt (API-first approach)
- Mikroserwisów — projektowanie kontraktów między serwisami (gRPC/Protobuf lub REST) z uwzględnieniem wersjonowania
- Design review i code review — weryfikacja czy nowe endpointy są zgodne ze standardami i spójne z istniejącym API
- Wewnętrznych API backendowych — spójność nawet wewnątrz organizacji redukuje koszty integracji i onboardingu
Ścieżka nauki #
API design to umiejętność łącząca wiedzę techniczną z myśleniem produktowym.
Zacznij od:
- Zasady REST — Richardson Maturity Model (poziomy 0-3), zasoby vs operacje
- Specyfikacja OpenAPI 3.x — pisanie schematów YAML, dokumentowanie w Swagger UI
- Narzędzia: Postman (testowanie i mock server), Swagger Editor, Stoplight Studio
- Analiza przykładów: GitHub REST API, Stripe API, Twilio API — wzorce z world-class API
Następnie poznaj:
- Wersjonowanie strategii: URL path vs header vs media type — zalety i wady każdego podejścia
- API-first development — najpierw kontrakt OpenAPI, potem implementacja; generowanie serwerowego i klienckiego kodu ze schematu
- GraphQL design — schema-first, resolver patterns, N+1 problem i DataLoader
- API security — rate limiting, OAuth2, API keys, CORS, walidacja wejścia
FAQ #
- Czym jest podejście API-first?
- API-first to strategia projektowania, w której interfejs API jest definiowany i dokumentowany (OpenAPI) przed implementacją. Pozwala na równoległą pracę frontend i backend, generowanie kodu ze schematu i wczesną walidację kontraktu z konsumentami API.
- Jak wersjonować REST API?
- Najczęściej przez URL path: /api/v1/ i /api/v2/ — proste i czytelne. Alternatywy: nagłówek Accept (application/vnd.api.v2+json) lub parametr query (?version=2). URL path dominuje w praktyce. Nigdy nie zmieniaj istniejących endpointów bez wersji — to breaking change.
- Co to jest OpenAPI / Swagger?
- OpenAPI (dawniej Swagger) to standard opisu REST API w formacie YAML lub JSON. Definiuje endpointy, parametry, schematy danych i kody statusu. Swagger UI generuje z pliku OpenAPI interaktywną dokumentację HTML. To de facto standard dokumentacji REST API.
- Kiedy używać GraphQL zamiast REST?
- GraphQL jest korzystny gdy klienci mają zróżnicowane potrzeby danych (np. mobile vs web), gdy chcemy unikać over-fetchingu lub gdy budujemy elastyczne publiczne API. REST sprawdza się lepiej dla prostych CRUD operacji, cache HTTP i gdy ważna jest prostota.