# Wzorce tworzenia API

URL: https://developertoolkit.ai/pl/cookbook/backend-recipes/api-patterns/
Description: Prompty dla Claude Code, Codex i Cursora, które budują idempotentne POST-y, paginację keyset i OpenAPI bez dryfu, plus testy, które to udowadniają.

Wzorce tworzenia API dla agentów kodujących to trzy poprawki produkcyjne: middleware z kluczem idempotencji, dzięki któremu ponowiony `POST` nigdy nie obciąży klienta dwa razy, paginacja keyset po unikalnym kluczu złożonym, która nie gubi wierszy na granicy strony, oraz dokument OpenAPI generowany ze schematów Zod używanych przez handlery. Każdy wzorzec ma test, który go udowadnia bez czytania kodu linijka po linijce.

Ten przepis jest dla backendowców, którzy pozwalają agentowi pisać endpointy i chcą dowodu, że te wytrzymają ponowienia, równoległe zapisy i zmiany schematu. Twój `POST /orders` obciąża klienta dwukrotnie, gdy aplikacja mobilna ponawia żądanie na słabym zasięgu. „Następna strona” pomija zamówienie za każdym razem, gdy dwa zamówienia mają to samo `created_at`. Plik OpenAPI rozjechał się z kodem trzy sprinty temu, więc wygenerowany klient wprowadza w błąd każdego frontendowca, który mu ufa. Wszystkie trzy błędy przechodzą code review, bo kod wygląda poprawnie. Pokazuje je dopiero test, który odtwarza awarię.

Bazowy stack to Express, TypeScript, Zod, Postgres i Redis. Prompty przenosisz na Fastify, NestJS albo Route Handlers w Next.js zmianą jednej linijki. Jeśli kontrakt nie jest jeszcze zaprojektowany, zacznij od [API spec-first z agentami](/pl/workflows/build/api-development/); ta strona zaczyna się tam, gdzie trasy już istnieją.

## Co wyniesiesz z tych wzorców API

- Prompt dodający endpoint zgodny z konwencjami repozytorium i sposób uruchomienia go w każdym narzędziu.
- Prompt na **middleware z kluczem idempotencji**, który rezerwuje klucz przed uruchomieniem handlera, więc dwa równoległe ponowienia nie obciążą klienta dwa razy.
- Prompt na **paginację keyset** z sortowaniem złożonym, pasującym indeksem i kursorem, który zachowuje precyzję mikrosekund.
- Prompt na **OpenAPI 3.1 ze schematów Zod** z krokiem CI, który pada, gdy specyfikacja jest nieaktualna.
- Przebieg weryfikacji, który zamienia to wszystko w dowody do sprawdzenia zamiast czytania kodu handlerów.

## Jak sprawić, żeby agent trzymał się istniejących konwencji tras?

Daj agentowi jedną istniejącą trasę jako wzorzec i zabroń nowych abstrakcji. Agent bez wzorca wymyśla własne klasy błędów, koperty odpowiedzi i helpery walidacji. Ten prompt działa we wszystkich trzech narzędziach.

**Prompt do wklejenia: nowy endpoint w stylu repozytorium**

```text
Read src/routes/users.ts and src/middleware/errors.ts first; they define our route conventions.
Then add POST /orders in src/routes/orders.ts:
- Validate the body with a Zod schema: items is a non-empty array of { sku: string, qty: int >= 1 }.
- Require an Idempotency-Key header (UUID). Do not put the key in the body.
- Return 201 with the created order. Return 400 with our existing error shape on validation failure.
- Reuse the existing error middleware and logger. Do not create new error classes, helpers, or dependencies.
- Add a Vitest + supertest test file next to the route covering 201, 400 (bad body), and 400 (missing header).
Stop after the tests pass and list every file you changed.
```

Sposób uruchomienia zależy od narzędzia. Zacznij w trybie planowania, żeby zatwierdzić listę plików, zanim cokolwiek zostanie zapisane.

**Cursor**

    W panelu Agent dołącz oba pliki z konwencjami przez `@src/routes/users.ts` i `@src/middleware/errors.ts`, a potem wklej prompt. Przy nowej trasie przełącz się najpierw na **Plan Mode**: Cursor tworzy plan implementacji przed napisaniem kodu, a ty zatwierdzasz listę plików. Potem pozwól agentowi uruchomić testy i przejrzyj diffy dla każdego pliku. Zacznij od pliku testów, nie od handlera.

**Claude Code**

    Uruchom prompt z katalogu głównego repozytorium w trybie planowania, żeby Claude Code zaproponował zmianę przed edycją:

    ```bash
    claude --permission-mode plan "$(cat prompts/add-orders-route.txt)"
    ```

    Po zatwierdzeniu planu Claude Code czyta pliki wzorcowe, edytuje i uruchamia testy. Żeby uruchomić ten sam prompt bez nadzoru w CI, użyj `claude -p` z `--output-format json` i jawną listą `--allowedTools`.

**Codex**

    Uruchom interaktywnie, z zapisem ograniczonym do workspace. Poniższy profil uprawnień jest w Codex CLI 0.157.1 w wersji beta. OpenAI zaleca go zamiast starszej flagi `--sandbox`; te dwa mechanizmy się nie łączą, więc nie używaj ich razem.

    ```bash
    codex -c 'default_permissions=":workspace"' -a on-request "$(cat prompts/add-orders-route.txt)"
    ```

    Przy uruchomieniu nieinteraktywnym daj `-a never` przed podkomendą (`codex -a never exec …`) i dodaj `-o result.md`, żeby zapisać końcowy raport agenta.

Zapisz prompt jako `prompts/add-orders-route.txt`, żeby cały zespół uruchamiał ten sam. To samo dotyczy każdego promptu na tej stronie.

## Jak powstrzymać ponowiony POST przed podwójnym obciążeniem?

Klient, któremu minął timeout, nie wie, czy serwer przetworzył żądanie, więc je ponawia. Rozwiązaniem jest nagłówek `Idempotency-Key`. Serwer zapisuje pierwszą odpowiedź pod tym kluczem i odtwarza ją przy każdym powtórzeniu. Agenci poprawnie piszą ścieżkę szczęśliwą. Gubią przypadek równoległy, bo naiwna wersja zapisuje odpowiedź dopiero *po* zakończeniu handlera. Dwa jednoczesne ponowienia trafiają wtedy na pusty cache i oba obciążają klienta.

**Prompt do wklejenia: middleware z kluczem idempotencji**

```text
Write Express middleware idempotency() in TypeScript, using the ioredis client exported from src/lib/redis.ts.
- Apply it to POST and PATCH. A missing Idempotency-Key header returns 400.
- Fingerprint the request as sha256(method + path + canonical JSON body).
- BEFORE calling the handler, claim the key atomically:
  SET idem:{key} '{"state":"processing","fp":"<fingerprint>"}' NX EX 86400.
- If the claim fails, read the entry:
  - different fingerprint -> 422, regardless of state (the key was reused for a different request)
  - else state "processing" -> 409 with Retry-After: 1
  - else state "done" -> replay the stored status and body with header Idempotent-Replay: true
- After the handler responds with status < 500, overwrite the entry with {state:"done", fp, status, body}, keeping the TTL.
- If the handler throws or returns 5xx, DEL the key so the client can retry.
- Also add a unique constraint on orders.idempotency_key in a new migration, as the backstop if Redis loses the key.
Tests (Vitest + supertest, real Redis from docker compose):
1. Same key twice in sequence: one row in orders, second response has Idempotent-Replay: true.
2. Same key, 10 requests in parallel with Promise.all: exactly one row, every response is 201 or 409.
3. Same key with a different body: 422.
4. Handler throws: key is released, a retry succeeds.
5. A different body sent while the first request is still processing: 422.
```

Dwie decyzje zostają po twojej stronie i żadnej nie widać w diffie. Pierwsza to **okno przechowywania**: TTL 24 godziny oznacza, że ponowienie drugiego dnia znowu obciąży klienta. Dopasuj TTL do najdłuższego okna ponowień najwolniejszego klienta, na przykład kolejki offline w aplikacji mobilnej. Druga: **Redis to cache**. Eksmisja albo failover gubi klucze i dlatego prompt żąda ograniczenia unikalności na `orders.idempotency_key`. Baza odrzuci drugi insert, nawet gdy Redis zapomniał o pierwszym. Najważniejszy jest test 2. Jeśli przechodzi przy 10 równoległych żądaniach, wyścig jest zamknięty, niezależnie od tego, jak middleware wygląda w środku.

## Jak paginować API bez gubienia i powtarzania wierszy?

Paginacja offsetowa (`?page=3&limit=20`) przesuwa się za każdym razem, gdy ktoś wstawi wiersz w trakcie przeglądania. Paginacja kursorem (keyset) to naprawia, ale agenci wprowadzają dwa cichsze błędy. Sortują po kolumnie nieunikalnej, więc wiersze o tym samym `created_at` znikają albo się powtarzają na granicy strony. Przepuszczają też znacznik czasu przez javascriptowy `Date`, który trzyma milisekundy, podczas gdy `timestamptz` w Postgresie przechowuje mikrosekundy. Efekt jest ten sam, nawet na danych, które wyglądają na unikalne.

**Prompt do wklejenia: paginacja keyset dla GET /orders**

```text
Implement cursor pagination for GET /orders (Express + TypeScript + pg) over
orders(id uuid primary key, created_at timestamptz not null, ...).
- Sort by (created_at DESC, id DESC). The cursor must identify one row uniquely.
- The cursor is base64url of JSON {c: created_at, i: id}. Select created_at as text
  (to_char(created_at at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')) so microseconds survive.
  Never pass it through a JS Date.
- Query: WHERE (created_at, id) < ($1::timestamptz, $2::uuid) ORDER BY created_at DESC, id DESC LIMIT $3 + 1.
  The extra row sets hasNextPage. No OFFSET anywhere. Every value is a bound parameter.
- limit defaults to 20, max 100. A malformed cursor returns 400 with our error shape.
- Response: { data: [...], pageInfo: { nextCursor: string | null, hasNextPage: boolean } }.
- Add a migration: CREATE INDEX orders_created_at_id_idx ON orders (created_at DESC, id DESC).
Tests against a real Postgres (testcontainers or docker compose):
1. Insert 57 rows where groups of 5 share an identical created_at, including microsecond differences.
   Walk every page with limit 10. Assert the union of ids equals the inserted set with no duplicates,
   in the exact expected order.
2. Insert a new row between page 1 and page 2. Assert page 2 neither repeats nor skips an existing row.
3. In the test transaction, run SET LOCAL enable_seqscan = off (or seed >= 10,000 rows and ANALYZE orders),
   then EXPLAIN the page query and assert the plan uses orders_created_at_id_idx.
```

Test 3 wyłącza skany sekwencyjne (albo wstawia do tabeli odpowiednio dużo wierszy), bo przy tabeli z 57 wierszami planer Postgresa słusznie wybiera skan sekwencyjny. Samo sprawdzenie EXPLAIN byłoby więc niestabilne, a agent, który zobaczy niestabilny test, osłabi go, zamiast poprawić zapytanie.

Żeby zaufać wynikowi, nie musisz czytać SQL-a. Test 1 to pełne przejście przez wszystkie strony: jeśli na dowolnej granicy strony zginie albo zdubluje się choć jeden wiersz, porównanie zbiorów pada. Żeby go poszerzyć, zamień stałe 57 wierszy na generowaną właściwość („dla dowolnego multizbioru znaczników czasu i dowolnego rozmiaru strony przejście przez strony zwraca każdy wiersz dokładnie raz”), tak jak opisuje to [testowanie oparte na właściwościach z agentami](/pl/workflows/test/property-based-testing/). Test 3 pilnuje wydajnościowej połowy wzorca. Bez indeksu złożonego zapytanie keyset jest poprawne, ale skanuje tabelę, co wychodzi dopiero na produkcji przy dużej skali. Pracę z indeksami i planami zapytań wykraczającą poza ten endpoint opisują [wzorce optymalizacji SQL](/pl/cookbook/database-recipes/sql-patterns/).

## Jak utrzymać specyfikację OpenAPI w zgodzie z kodem?

Ręcznie pisana specyfikacja się rozjeżdża, bo nic nie pada, gdy staje się nieaktualna. Generuj ją ze schematów Zod, których handlery i tak używają do walidacji, commituj wynik i pozwól CI paść, gdy zacommitowany plik różni się od świeżo wygenerowanego. `@asteasolutions/zod-to-openapi` (npm, 9.1.0 na 2026-09-26) buduje dokumenty OpenAPI 3.x z zarejestrowanych schematów Zod.

**Prompt do wklejenia: OpenAPI 3.1 generowane z Zod**

```text
Every route in src/routes/ validates with Zod schemas defined next to the handler.
Wire up @asteasolutions/zod-to-openapi (add it to package.json; check the version with npm view first):
- Register each route's params, query, body, and every response status schema with one OpenAPIRegistry
  in src/openapi/registry.ts. Import the SAME schema objects the handlers use; do not redeclare them.
- Add the bearer JWT security scheme and apply it to every route that uses our auth middleware.
- Add a script "openapi:gen" that writes openapi.json (OpenAPI 3.1) at the repo root, with keys sorted
  so the output is deterministic.
- Add a CI step: run openapi:gen, then `git diff --exit-code openapi.json`. The step fails if the committed
  spec is stale.
- Do not hand-write any path, parameter, or response. If a route has no Zod schema, list it and stop.
```

To krok `git diff --exit-code` utrzymuje specyfikację aktualną. Jest pewniejszy niż test porównujący w pamięci, bo sprawdza dokładnie ten plik, który pobierają konsumenci. Sprawdź wynik linterem: `npx @redocly/cli lint openapi.json` (Redocly CLI 2.54.3 na 2026-09-26), żeby wyłapać brakujące identyfikatory operacji i niezadeklarowane zabezpieczenia. Gdy trasa nie ma schematu, prompt każe agentowi się zatrzymać, a nie go wymyślać. Agent, który „uzupełnia lukę”, pisze dokładnie tę ręcznie utrzymywaną specyfikację, której próbujesz się pozbyć.

## Jak zweryfikować kod API od agenta bez czytania każdej linijki?

Uruchom serwis i zaatakuj go jego własnym kontraktem. Schemathesis (PyPI, 4.28.0 na 2026-09-26) czyta `openapi.json`, generuje poprawne i niepoprawne żądania dla każdej operacji i sprawdza każdą odpowiedź względem specyfikacji: błędy serwera, kody statusu, schematy odpowiedzi i to, czy niepoprawne wejście jest odrzucane.

```bash
# Terminal, with the API running locally on port 3000
uvx schemathesis run openapi.json --url http://localhost:3000 --checks all --max-time 120
```

Zielony przebieg Schemathesis, test równoległości i test przejścia przez strony razem dowodzą więcej niż uważna lektura handlerów. Oddaj cały przebieg agentowi i poproś o wynik w formie dowodów, a nie podsumowania.

**Prompt do wklejenia: pakiet dowodów dla zmiany w API**

```text
Run these and report each result verbatim (command, exit code, last 20 lines of output). Do not fix anything yet:
1. npm test -- orders          (idempotency and pagination suites)
2. npm run openapi:gen && git diff --stat openapi.json
3. npx @redocly/cli lint openapi.json
4. Start the API, then: uvx schemathesis run openapi.json --url http://localhost:3000 --checks all --max-time 120
Then write a section for the PR description titled "Evidence" with:
- a table of the four checks and pass/fail,
- the openapi.json diff summarised as added / changed / removed operations, marking any breaking change
  (removed field, narrowed type, new required parameter),
- every test you added or changed, one line each with what it proves.
If any check fails, stop and show the failure. Do not weaken a test or an assertion to make it pass.
```

W efekcie zmienia się to, co czyta recenzent. Czyta diff `openapi.json` (kontrakt) i tabelę dowodów, a nie middleware. Zmiana kontraktu, która usuwa albo zawęża pole, wymaga akceptacji zespołu, który konsumuje API. Zmiana bez diffu kontraktu i z zielonymi testami potrzebuje tylko akceptacji zespołu-właściciela. Strona o [pakiecie dowodów, który musi nieść pull request agenta](/pl/workflows/ship/evidence-bundle/), zamienia to w kontrakt PR-a z kontrolą w CI. [Ochrona wyroczni](/pl/workflows/test/protect-the-oracle/) omawia regułę z ostatniej linijki promptu: agent nie może edytować testów, które go oceniają.

## Jak otworzyć pull request ze zmianą API przez serwer MCP GitHuba?

Gdy specyfikacja się zmienia, agent może otworzyć pull request, dołączyć sekcję z dowodami i poprosić o review zespół konsumujący API przez oficjalny serwer MCP GitHuba. Zdalny serwer pod `https://api.githubcopilot.com/mcp/` we wszystkich trzech klientach przyjmuje osobisty token dostępu GitHuba (PAT) w nagłówku `Authorization`. Polecenia poniżej używają PAT-u trzymanego w zmiennej środowiskowej, nigdy w zacommitowanym pliku.

**Cursor**

    Dodaj serwer `github` z adresem `https://api.githubcopilot.com/mcp/` i nagłówkiem `Authorization: Bearer` w `~/.cursor/mcp.json` (twoja konfiguracja użytkownika, poza repozytorium). Dokładny JSON znajdziesz w [przewodniku po serwerze MCP GitHuba](/pl/ecosystem/mcp/github-mcp/).

**Claude Code**

    ```bash
    claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
      -H "Authorization: Bearer $GITHUB_PAT"
    ```

**Codex**

    ```bash
    codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT
    ```

Jeśli agent ma już CLI `gh` i dostęp do powłoki, `gh pr create --body-file evidence.md` zrobi to samo mniejszym kosztem tokenów. Serwer MCP wybierz wtedy, gdy agent ma też czytać logi CI i komentarze z review bez dostępu do powłoki.

## Kiedy wzorce API napisane przez agenta zawodzą na produkcji

**Tryby awarii i jak z nich wyjść**

- **Kontrola idempotencji przegrywa wyścig sama ze sobą.** Odpowiedź jest zapisywana po handlerze, więc równoległe ponowienia obciążają dwa razy. *Naprawa:* znajdź duplikaty zapytaniem `SELECT idempotency_key, count(*) FROM orders GROUP BY 1 HAVING count(*) > 1`, zwróć środki, dodaj ograniczenie unikalności i wymagaj testu z 10 równoległymi żądaniami przed merge'em.
- **Klucze znikają z Redisa.** Polityka eksmisji taka jak `allkeys-lru` usuwa wpisy idempotencji, gdy brakuje pamięci. *Naprawa:* trzymaj klucze idempotencji w osobnej bazie lub instancji Redisa z `noeviction`, a ograniczenie w bazie danych traktuj jako zabezpieczenie ostatniej linii.
- **Paginacja gubi wiersze, które wyglądają na unikalne.** Kursor niesie milisekundowy `Date`, a kolumna przechowuje mikrosekundy. *Naprawa:* koduj znacznik czasu jako tekst z Postgresa i dodaj do testu przejścia przez strony wiersze różniące się mikrosekundami.
- **`OFFSET` wraca w kolejnej zmianie.** Inna sesja agenta „upraszcza” zapytanie. *Naprawa:* test przejścia przez strony ze wstawieniem w połowie pada. Trzymaj go w domyślnym przebiegu testów, a nie w wolnym zestawie, którego nikt nie uruchamia.
- **Specyfikacja i tak się dezaktualizuje.** Ktoś dodaje trasę bez rejestracji schematu, więc generator jej nie widzi. *Naprawa:* dodaj test, który wylicza trasy routera Expressa i pada dla każdej trasy nieobecnej w rejestrze.
- **Agent wymyśla pakiet.** Wiarygodnie brzmiące nazwy, takie jak `express-idempotent-middleware`, nie istnieją w npm (sprawdzone 2026-09-26). *Naprawa:* uruchom `npm view <package> version` dla każdej zależności dodanej przez agenta, a bramkę w CI opisuje [weryfikacja zależności](/pl/workflows/test/dependency-verification/).
- **Odpowiedzi błędów ujawniają wnętrze systemu.** Wygenerowane handlery wkładają surowy błąd bazy do `details`. *Naprawa:* zwracaj stabilny kod błędu i `traceId`, błąd bazy loguj po stronie serwera i dodaj przebieg Schemathesis do CI, żeby każda odpowiedź 500 kończyła build błędem.
- **Nadmiarowe dodatki, o które nikt nie prosił.** Poproszony o „najlepsze praktyki REST” agent dokłada koperty HATEOAS `_links`, których nie czyta żaden klient. *Naprawa:* nazwij kształt odpowiedzi w prompcie, tak jak robi to każdy prompt na tej stronie.

## Dokąd dalej po wzorcach API

- [API spec-first z agentami](/pl/workflows/build/api-development/): zaprojektuj kontrakt, uwierzytelnianie i wersjonowanie, zanim powstaną trasy z tej strony.
- [Automatyzacja testów API](/pl/workflows/test/api-testing/): testy kontraktowe i testy konsumentów, które rozszerzają przebieg Schemathesis.
- [Receptury Node.js i Express](/pl/cookbook/backend-recipes/node-patterns/): uwierzytelnianie JWT, rate limiting i zadania w tle na tym samym stacku.
- [Wzorce rozwoju serverless](/pl/cookbook/backend-recipes/serverless-patterns/): wdrażanie tych API do funkcji i na edge, gdzie idempotencja ma jeszcze większe znaczenie.
- [Czytanie dowodów zamiast kodu](/pl/ladder/evidence-not-diffs/): dlaczego recenzent z tej strony czyta kontrakt i wyniki testów zamiast kodu.
