Rozdział 1: Podstawy

Dla kogo jest to szkolenie i co chcemy osiągnąć

Patrz - wstęp powyżej.

O czym będzie, trzy podstawowe przypadki użycia REST API

Patrz - wstęp powyżej.

O czym NIE będzie

Nie skupiamy się na kryptografii, hardeningu, podatnościach bezpieczeństwa ani pentestach - ale przy projektowaniu REST API będziemy zapobiegać lukom bezpieczeństwa wynikającym z niewłaściwej architektury (np. IDOR - możliwość enumeracji zasobów).

Nie będziemy mówić o autoskalowaniu infrastruktury, zasygnalizujemy jedynie, gdy omawiane zagadnienie będzie związane z rozmiarem projektu. Podobnie z testami - nie uczymy zasad tworzenia testów jednostkowych czy integracyjnych, ale wskażemy nieoczywiste aspekty testowania API warte uwzględnienia.

Nie będzie o konkretnym frameworku ani języku, nie będzie o websocketach, nie będzie o GraphQL, nie będzie o multimediach ani streamowaniu audio/wideo. Nie będziemy wchodzić w procesy biznesowe e-commerce ani rozważać atomowości zmiany stanów magazynowych - w szkoleniu skupiamy się na sposobach komunikowania tego stanu.

Protokół HTTP/HTTPS

Celem tego rozdziału jest wyrównanie poziomu wiedzy na temat naszego podstawowego protokołu komunikacyjnego, jakim jest HTTP(S). Znajdziemy tu omówienie protokołu, objaśnienie wszystkich elementów URL-a, poznamy główne cechy żądań i odpowiedzi, nauczymy się ręcznej komunikacji przez HTTP (umiejętność ta raczej się nie przyda, ale buduje głębsze zrozumienie tematu). Dowiemy się, w jaki sposób diagnozować problemy z komunikacją za pomocą narzędzi developerskich przeglądarki oraz narzędzia curl. Na końcu przeczytamy, co nowego doszło w protokołach HTTP 2 oraz HTTP 3.

Narzędzia, które warto poznać

Podstawowe narzędzia przydatne na początku - curl, httpie, Yaak, OpenAPI itp.

Absolutnie podstawowe, minimalne REST API

Bierzemy na tapet najprostsze, najbardziej podstawowe REST API fikcyjnego narzędzia z listą zadań TODO, przyjmujące żądania typu GET i POST, zwracające odpowiedzi w formacie JSON. Dodatkowo: dlaczego używać https także w developmencie, bez redirectów i nigdy po IP, oraz dlaczego warto trzymać API pod inną (sub)domeną niż witryna produktowa.

Jak wersjonować API

Przy projektowaniu API nie myślimy z reguły o tym, że kiedyś zastąpimy je wersją 2.0 zaś wersję 1.0 trzeba będzie w przewidywalny i cywilizowany sposób wycofać z użycia (deprecate). Meaningful versioning, semantic versioning; routowanie do różnych wersji nie wymagające deserializacji; symbol wersji na początku czy w środku czy poza URL-em; tylko prototyp może zmieniać się często i bez zgodności wstecznej; zagadnienie kompatybilność API w tył i w przód; inne możliwości wersjonowania.

Jak komunikować wersjonowanie API

changelog, przewodniki migracji, onboarding deweloperów; dodanie opcjonalnego pola = bezpieczne; usunięcie/zwężenie/zmiana typu = łamiące; nowa wartość enuma = to zależy; jak to robią w protobufach.

Wycofywanie wersji (albo mniejszych fragmentów)

osobny URL od sprawdzania aktualności i kompatybilności; nagłówki RFC 8594 Sunset HTTP Header do rozważenia, ale łatwiej osadzić informację w zwracanym obiekcie.

Status pages

gdzie stawiać (zewnętrzna infrastruktura), kiedy powiadamiać, jak często aktualizować, gdzie wyświetlać (pasek na głównej ma sens), dlaczego duzi dostawcy bardzo o tym kłamią, dlaczego czasem naprawdę nie wiedzą (bo np. cloudflare zepsuł ale tylko pół regionu); jak wynagradzać klienta; SLA / SLO / SLI.

Konwencje nazewnictwa ścieżek w endpointach czyli czasowniki kontra rzeczowniki

Omówienie popularnych opcji; sztuczne klucze w ID-kach zamiast ujawniania danych, opcjonalny slug może być wygodny dla użytkownika, konwencje nazewnictwa pól, kodowanie enumów.

Jak traktować wchodzący i wychodzący content-type

czasem coś co wygląda jak json zostanie automatycznie zdeserializowane, niektóre API będą wymuszać prawidłowy content-type; kompresja odpowiedzi jeśli klient się zgadza; chunked max length; tylko angielski i nic więcej - zaoszczędzisz czas a developerzy i tak nie znoszą tłumaczeń bo nie da się wtedy googlać błędów.

Czy i do czego używać statusu odpowiedzi HTTP

Wiele tutoriali robi tu złą robotę. Konwencje, które w małym projekciku mają sens, wywracają spójność dużego projektu zbudowanego z wielu komponentów. Uwaga na przezroczyste przekierowania w serwerach i klientach. Których metod HTTP będziemy używać, dlaczego upsert nie pasuje do konwencji i tak dalej.

Proponowany ogólny schemat każdej odpowiedzi

Podsumowanie powyższych rozdziałów: status, pole z odpowiedzią, ostrzeżenie o kompatybilności, ostrzeżenie o pracach serwisowych.

Dobre komunikaty błędów

Czyli co zamiast „błąd w kolumnie 18282”. Kontrola GET czy POST; override standard errors pages; „czy miałeś na myśli”; URL do bazy wiedzy; kody błędu gdy opis nie jest unikalny; Problem Details (RFC 9457) do rozważenia. Błędy formularzy - zwracanie wszystkich błędów walidacji naraz; sygnał „czy można ponawiać”.

Dygresja: warstwy abstrakcji przy tworzeniu klientów

Im bardziej customowe rzeczy robimy, tym ważniejsze są warstwy abstrakcji - jedna bierze obiekt, druga bierze string, trzecia bierze strumień. Abstrakcje zawsze ciekną.

OpenAPI

O potrzebie posiadania jednego źródła prawdy; generowanie dokumentacji; co jest teraz a co będzie w wersji 4.0, OpenAPI nie będzie panaceum, np. Cloudflare generuje openapi z typescriptu.

Generowanie serwerów i klientów z OpenAPI

Zaleta - użycie takich samych encji; dokumentowanie obejść; wady.

Czy warto wydawać oficjalne SDK, howto, tutoriale

Jeśli produkt będzie popularny, to za darmo powstaną nieoficjalne; które potem można sforkować/przejąć/zatrudnić; SDK dostarcza silne typy ale także operacje asynchroniczne, SDK może dostarczać preferowane timeouty, sposób obsługi błędów albo pre-walidację zmniejszającą obciążenie serwera, każda publikacja ciągnie za sobą konieczność aktualizowania; cykl życia spowalnia iteracje i wymaga zasobów.

Konwencje z jsonapi.org

Opis, co ma sens a co nie bardzo; uwzględnić sparse fieldsets (?fields=), dołączanie powiązanych zasobów (?include=/embedding vs linkowanie).

Zasoby-singletony

/me, /settings, /config. Wzorzec „bieżący użytkownik” i zasoby jednoznaczne (bez ID w ścieżce).

Udostępnianie klientom Postmana

O wymaganych nagłówkach CORS.

Generowanie klientów z modelu danych

czy ścieżki API mają odwzorować relacje, np. users/123/cart/456; często klient i serwer będą pisane w różnych językach; reference client do łatwego porównania z implementacją produkcyjną.

Daty, godziny i strefy czasowe

Tu żyją smoki. Serio. W tym rozdziale będę starał się przekonać cię, by wszystkie timestampy trzymać w postaci UTC oraz by upraszczać architekturę i raczej dać wszystkim darmowe 23h usług, niż obsługiwać reklamację użytkownika przeprowadzającego się z Nowej Zelandii na Hawaje. ISO 8601-formatted strings, ISO 8601 durations, interwały, powtarzalność (np. dla rate-limit window, retencji, subskrypcji).

Drobiazgi

ignoruj slashe na końcu ścieżki (raczej interpretuj jako ten sam zasób niż redir), health endpoint, readiness endpoint, nie zwracaj arrayów jako głównej odpowiedzi (rozszerzalność o metadane / paginację), integracje przez n8n albo make albo zapier; unikaj tworzenia wewnętrznych API; Pieniądze / waluty / precyzja dziesiętna; nie przeliczaj walut, ceny to decyzja biznesowa a nie projektowa.

Projektowanie API MCP dla AI/LLM

tutaj co nieco o API dla AI, ale także by uważać i nie ujawniać swoich kluczy; oraz o tym że LLM może używać CLI.

Dodatkowa wiedza o tworzeniu API klient-serwer

CORS. Preflight, Access-Control-*, credentials, czemu „*” gryzie się z cookies. HEAD i OPTIONS poza CORS. HEAD do taniego sprawdzenia istnienia/rozmiaru bez body; OPTIONS jako deklaracja możliwości.

Dlaczego nie będzie o projektowaniu zmian i governance

Każda firma, dział, zespół i PM wykształca własny zestaw sposobów na zarządzanie, więc będzie tylko garść porad: niech przepychanie wniosku o zmianę będzie zadaniem jednej osoby a nie zespołu; ta osoba musi znać problem wzdłuż i wszerz; ADR niestety oprócz rozwiązań technicznych musi też być zarządzany politycznie.

Rozdział 2: Rzeczy średnio skomplikowane

Autoryzacja i uwierzytelnianie

Nie ma słowa autentykacja, 401 vs 403, dodać testy sprawdzające czy wszystkie endpointy są chronione (brak ochrony to wyjątek).

przegląd schematów: API key, OAuth2 (client-credentials dla M2M, auth-code dla aplikacji), JWT (i kiedy świadomie NIE — bo unieważnienie jest trudne), mTLS, podpisywanie żądań (HMAC) — z kryterium „kiedy co”; cyklu życia poświadczeń: wydawanie, rotacja, unieważnianie, wygasanie, refresh, scopes/ograniczanie uprawnień klucza, gdzie i jak klient klucz pozyskuje.

Zarządzanie sesjami

Nie ma jednego dobrego sposobu. Token w URL-u, token w cookies, token w nagłówkach, token w requeście. CSRF, SameSite, double-submit; Zasoby z czasem życia - TTL / rezerwacje np. koszyk / rezerwacja ważna 10 min, potem wygasa — jak to wyrazić w kontrakcie.

Role i dostępy

czy zapewnia je system zewnętrzny, czy implementacja API, czy filtrujemy po tabelach, kolumnach, wierszach, czy API jest z tym zgodne; czy ukryte dane da się pozyskać na około; jawna kontrola własności obiektu.

Walidacja danych wejściowych

komunikatami błędów pomożemy userom i włamywaczom ale security by obscurity i tak nie działa; limity połączeń, zip bomby; czy sanityzować w bazie czy na UI; UTF-8 wszędzie, normalizacja napisów, pułapki przy porównywaniu loginów/identyfikatorów, emoji, case-folding.

ORM w danych

Czy drzewo zależnych obiektów jesteśmy w stanie tworzyć atomowo? Czy głębokość ORM w deserializacji jest sterowana? Jaki jest default? Problemy z reprezentacją relacji w formacie JSON.

Filtrowanie i sortowanie wyników

Uwaga na SQL injection; ULID; limit długości URL-a w GET, wyszukiwanie z ciałem żądania nową metodą QUERY gdy kryteriów jest dużo, sygnalizacja wyszukiwania pełnotekstowego; pusta kolekcja = 200 [], nie 404; null vs [] vs brak pola w odpowiedzi.

Stronicowanie wyników

gruby temat, mocno zależy do skali, side efekty zależne od przyjętej konwencji.

Rate limits czyli limitowanie ruchu

W jaki sposób realizować limity wynikające z wykupionego tiera, jak poradzić sobie z klientem którego kod poszedł w maliny; sliding window rate limiting per API key and IP; IETF draft: RateLimit Header Fields (RateLimit, RateLimit-Policy); kontrakt odpowiedzi (429 + Retry-After).

O zliczaniu zasobów

uwaga na równoległe zadania oraz jak podejść do sytuacji w której klient wyczerpuje limit zasobów; kwota rozliczeniowa/metering (billing).

Timeouty nie istnieją, są tylko niedostarczone bajty

Na każdym poziomie abstrakcji timeout będzie czym innym, ale zawsze będzie to problem dwóch generałów.

Dygresja: na jakim poziomie sterować retry’ami

Plusy i minusy decyzji na różnym poziomie abstrakcji.

Dodatek: statystyki użycia zasobów dla klienta (oraz dla supportu)

Loguj wszystko, supportowi pokazuj wszystko, klientowi pokazuj dane zagregowane.

Aktualizacja danych - niekoniecznie PATCH

Semantyka null / brak pola / wartość pusta; czy null kasuje, czy brak pola = „nie zmieniaj”; które pola są read-only i co się dzieje przy próbie ich zmiany, co się dzieje przy próbie zmiany nieistniejących atrybutów, JSON Merge Patch (RFC 7386) vs JSON Patch (RFC 6902).

Generatory danych testowych i testy obciążeniowe

Historyjka z dawnych czasów i generatory sensownie wyglądających danych.

API default open / default close

Mikroserwisy albo usługi zależne mogą nie odpowiadać w zakładanym czasie, co wtedy robić; fail open z flagą informującą o degradacji.

Operacje asynchroniczne kontra synchroniczne

Kiedy przyjmować zadanie do kolejki a kiedy obsługiwać je natychmiast; 202 Accepted + zasób statusu + polling/Location/Retry-After.

Kontraktowa spójność danych

read-after-write czy eventual consistency? bardzo zależy od budowy infrastruktury, możliwości przyklejenia klienta do jednej maszyny na load balancerze, itp.

Upload i download plików

multipart vs base64-w-JSON vs presigned URL (klient wgrywa wprost do storage, serwer tylko podpisuje), limity rozmiaru ciała, skanowanie; bulk export dużych zbiorów. Odwrotność uploadu: żądanie eksportu → zadanie async → pobierz plik.

Po co komu CLI

Dla testerów, do integracji LLM, do automatyzacji, z wyjściem JSON; warto mieć wewnętrzne CLI jako reference client; bardzo warto trzymać się przyjętych konwencji, np. exit codes, dobrze jest integrować się z istniejącą infrą np. uwierzytelnianie w K8S i tak dalej.

Generowanie klientów CLI

Jak generować stronę serwerową i kliencką i utrzymywać zgodność w obie strony; uwierzytelnianie w środowisku headless/CI.

A może Protocol Buffers zamiast JSON-a?

Kiedy lepiej sprawdzi się protobuf, co jest tam wymyślone dobrze.

Dlaczego nie mówimy o gRPC/JSONRPC?

Czyli jak wykonywać akcje po stronie serwera bez udawania, że to odwołanie do zasobów REST.

Problemy z JSON-em i serializacją

Brak typu datetime, brak reprezentowalnych zakresów; brak reprezentacji zależności cyklicznych i WIELE innych.

OpenAPI dla średnio zaawansowanych

Jak utworzyć definicję OpenAPI w już istniejącym projekcie.

Model danych dla średnio zaawansownych

dodawaj symetryczne możliwości odpytywania, inaczej będzie full scan; Granularność zasobu: chatty vs chunky, granice agregatu. Czy GET /order zwraca też pozycje i adres, czy trzy osobne calle? Over-fetch vs N+1 po stronie klienta mobilnego; Relacje, embedding vs linkowanie, semantyka kaskad. Co się dzieje z dziećmi po skasowaniu rodzica (kaskada / 409 / osierocenie), nullowalne FK, jak reprezentować i modyfikować relacje. Ścieżki users/123/cart/456 są wzmiankowane, ale bez semantyki integralności.

Edycja wielu encji naraz

Oraz że bez sensu mieć HTTP 207 multi cośtam, nie należy też wymuszać na klientach pamiętania requestów, ogólnie batch API ma definiować semantykę - czy failuje w całości, czy robi revert, czy robi sekwencyjnie, czy przerywa; raportowanie zawsze granularne.

Jak sprzedawać dostęp do płatnego API

porady dotyczące oferty komercyjnej; SSO, RBAC, SOC-II i inne certyfikaty, logi audytowe; będzie nowy zestaw problemów: scraping, credential stuffing, account takeover, tworzenie tysięcy darmowych kont.

Architektura multi-tenant

Czyli osobne deploymenty dla osobnych klientów: współdzielona baza + tenant_id, schema-per-tenant, deployment-per-tenant, sposób identyfikacji tenanta (subdomena / nagłówek / token), izolacja danych, „noisy neighbor”; customowe SLA; customowa instalacja która odbiega od dalszego rozwoju, fajnie to robi Basecamp.

Zarządzanie pamięcią cache klienta

rzadko poruszany temat, osobna domena na zasoby statyczne, osobna na user generated, oprócz tego polecane dwa tiery - brak cache i krótki cache; ETag Cache-Control, Expires, Pragma, Last-Modified; ETag + If-Match, If-Unmodified-Since, wykrywanie „ktoś nadpisał w międzyczasie”. To bardzo częsty realny problem. RFC 9110/9111; Vary. Bez niego CDN/proxy potrafi podać odpowiedź jednego użytkownika drugiemu, gdy treść zależy od Authorization/Accept/Accept-Encoding; Dodatkowo: Cache-Control: private/no-store.

Infrastruktura serwerowa / cloudflare / cdn / proxy itp

Kim był serwerow? Rate limiting, DDoS protection, TLS termination, Request normalization, Geographic routing.

Webhooki

API oddzwania do klienta (zdarzenia). Ogromny temat produktowy: dostarczanie at-least-once, podpisywanie (HMAC), retry, idempotencja po stronie odbiorcy, ochrona przed SSRF, replay; CloudEvents jako koperta zdarzeń. Standardowy format webhooka/eventu (źródło, typ, id, czas) zamiast wymyślania własnego. „Cienkie vs grube” zdarzenia (event-carried state). Czy webhook niesie pełny stan, czy tylko identyfikator danych.

Sandboxy

gdy API jako produkt - sandbox dla klientów (testowe klucze, dane-zabawki, brak skutków ubocznych); możliwość klonowania proda, wiele endpointów albo przełącznik prod-sandbox; fejkowe kwoty wymuszające określone odpowiedzi.

Dobre rady dotyczące wydajności

Warto prowadzić testy na bazie wypełnionej tak, jak za rok będzie wypełniona produkcja. Warto śledzić czas wykonania testów - oraz śledzić regresje. Warto dodać stress-testy i śledzić, co jest w danej chwili wąskim gardłem.

Rozdział 3: Rzeczy skomplikowane

JSON Schema - czy pomoże?

Być może. W protobufach fajne jest to, że telegram sam się waliduje względem niezbędnego w tym przypadku pliku definicji.

Logowanie zdarzeń / telemetria

opentelemetry? co zapisywać? 100% of 500s, exceptions, failures; zapisuj wolne połączenia - wszystko powyżej p99 latency threshold; do tego: nazwani userzy, nazwani klienci; konta testowe; oflagowane sesje; reszta losowo - 1-5%.

Bezpieczne logowanie - SecretString

Jak logować informacje aby przeszły audyt, jak secret string, anonimizowanie dumpów proda.

GDPR, retencja, prawo do zapomnienia

techniczny konflikt między trzymaniem spójnych backupów a prawem do zapomnienia, nie cytujcie mnie ale w praktyce nikt nie przepisuje backupów, natomiast trzeba backupować osobno listę kluczy encji zapomnianych i w procedurze przywracania backupu mieć proces ponownego kasowania; logi można trzymać jeśli będą pseudoanonimizowane; audyty i historia zasobów - kto i kiedy.

Geoblokowanie / Sankcje / kontrola eksportu

nie tylko odrzucenie ataków z Białorusi czy Korei - świadome odrzucanie ruchu z określonych jurysdykcji — realny wymóg produktów komercyjnych.

Unikanie enumeracji zasobów

Jakie pułapki mamy w UUID różnych wersji, oraz stabilne czasowo generatory IDków czyli ULID albo uuidv7; osobne pule / prefiksy uidów dla różnych tabel.

Idempotencja - jak implementować

Wskazówki dotyczące implementacji endpointów; jest na to RFC IETF draft: Idempotency-Key Header; używać zawsze zegara serwerowego; Identyfikatory generowane przez klienta (PUT-create). Klient dostarcza UUID/ULID, dzięki czemu tworzenie jest idempotentne bez Idempotency-Key.

Losowe błędy w dev, test i preprod API

Dlaczego warto; dodatkowo o requestach zagregowanych np. aby nie mieć 20 calli z mobilki i 2^20 błędów tylko jeden call.

Przeciwdziałanie atakom Denial of Service (DoS)

Tutaj o tym, że trzeba bronić API przed wysyceniem zasobów, np. poprzez filtrowanie nieuprawnionych żądań powodujących pracochłonne obliczenia po stronie serwera.

circuit breakers, exponential backoff, backpressure

bezpieczniki, disabling features on demand twitter load, CAPTCHA or proof-of-work challenges after suspicious activity.

compatibility flags, compatibility dates

kompatybilność wsteczna.

dodatkowe testowanie API

celowe spowalnianie API w testach - co daje np. zobaczymy słabości klienta mobilnego; sprawdźmy choć raz wydajność generując 10x więcej danych niż przewidujemy na produkcji; testowanie malformed JSON unterminated strings i innych usterek.

Impersonacja konta użytkownika

Aby odtworzyć problem, support może potrzebować zalogować się na konto użytkownika - tutaj wskazówki dotyczące implementacji tej funkcji - audyt musi wyraźnie zaznaczać, co zrobił pracownik impersonując.

Zaawansowany JSON - niebezpieczeństwa i pułapki

Przykłady problemów związanych z deserializacją i serializacją JSON, jak np. przekroczenie granicy za którą liczby zmiennoprzecinkowe nie pokrywają wszystkich liczb naturalnych (problem z Twitterem/X i identyfikatorami tweetnięć). Streamowanie JSON-a (JSON Lines, NDJSON, JSON Text Sequences, Server-Sent Events (SSE)) aby mieć wyniki przyrostowe - mało popularne, podatne na problemy z buforowaniem, raczej korzysta się z websocketów czyli poza zakresem szkolenia; NaN/Infinity/liczby spoza zakresu w JSON.

Migracje, drain before restart

rollouty stopniowe z nowymi binarkami - jak robić routing; Migracje danych bez przestoju. Zmiana schematu pod żywym API: dual-write/dual-read, backfill, ekspansja-kontrakcja.

Automatyczne rollbacki

trzeba to powiązać z infrastrukturą, dzięki k8s nie jest już zarezerwowane dla największych, rollback z powodu degradacji jest nieoczywisty ale rollback częściowego deploymentu serwisu który nie zgłasza gotowości jest łatwy.

Observability

Tutaj większość będzie tylko zasygnalizowana, jeden dashboard czyni cuda, dashboardy działają najlepiej gdy pozwalają na szybkie filtrowanie i wizualizację kryteriów, więc lepiej grafana niż homemade, np. 20% faili zapytań to klienci z jednego z pięciu serwerów czy jeden kraj czy jeden dostawca płatności itp.

lista pytań: ile żądań, ile per endpoint, nagłówek, osobne pole.

Traceability

temat zwracania klientowi identyfikatora żądania (np. X-Request-Id, W3C traceparent) — do cytowania supportowi i do śledzenia rozproszonego. To element kontraktu odpowiedzi, a nie tylko logowania, więc nie domyka go Observability ani Bezpieczne logowanie. Naturalnie łączy się z dobrymi komunikatami błędów („podaj ten identyfikator supportowi”) i z impersonacją.