API Development Patterns

API development patterns for coding agents are three production fixes: idempotency-key middleware so a retried POST never charges twice, keyset pagination on a unique composite key so no row is dropped at a page boundary, and an OpenAPI document generated from the handlers’ Zod schemas. Each pattern ships with a test that proves it without a line-by-line review.

This recipe is for backend developers who let an agent write endpoints and want proof that they hold under retries, concurrent writes, and schema changes. Your POST /orders charges a customer twice when the mobile app retries on a weak connection. Your “next page” skips an order whenever two orders share a created_at. The OpenAPI file drifted from the code three sprints ago, so the generated client is wrong for every frontend developer who trusts it. All three bugs pass code review, because the code looks correct. Only a test that runs the failure shows the bug.

The anchor stack is Express, TypeScript, Zod, Postgres, and Redis. The prompts port to Fastify, NestJS, or Next.js Route Handlers with a one-line change. If you have not designed the contract yet, start with spec-first API development with agents; this page picks up once the routes exist.

What you’ll walk away with from these API patterns

• A convention-matching prompt for a new endpoint, and how to launch it in each tool.
• An idempotency-key middleware prompt that claims the key before the handler runs, so two concurrent retries cannot both charge.
• A keyset pagination prompt with a composite sort, a matching index, and a cursor that keeps microsecond precision.
• An OpenAPI 3.1 from Zod prompt with a CI check that fails when the spec is stale.
• A verification run that turns all of this into evidence you check instead of reading the handler code.

How do you get an agent to follow your existing route conventions?

Give the agent one existing route as the reference and forbid new abstractions. Agents that are not shown a reference invent their own error classes, response envelopes, and validation helpers. This prompt works in all three tools.

Copy-paste prompt: add an endpoint in the house style

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.

How you launch it depends on the tool. Start in a planning mode, so you approve the file list before anything is written.

Cursor

In the Agent panel, reference the two convention files with @src/routes/users.ts and @src/middleware/errors.ts, and paste the prompt. Switch to Plan Mode first for a new route: it writes an implementation plan before any code, and you confirm the file list. Then let Agent run the tests and review the per-file diffs it shows. Look first at the test file, not the handler.

Claude Code

Run it from the repository root in plan mode, so Claude Code proposes the change before editing:

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

Approve the plan, and Claude Code reads the reference files, edits, and runs the test command. To run the same prompt unattended in CI, use claude -p with --output-format json and an explicit --allowedTools list.

Codex

Run it interactively with writes confined to the workspace. The permission profile below is beta in Codex CLI 0.157.1. OpenAI now prefers it over the legacy --sandbox flag, and the two do not compose, so do not combine them.

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

For a non-interactive run, put -a never before the subcommand (codex -a never exec …) and add -o result.md to capture the agent’s final report.

Save the prompt as prompts/add-orders-route.txt so the whole team runs the same one. The same pattern applies to every prompt on this page.

How do you stop a retried POST from charging twice?

A client that times out cannot tell whether the server processed the request, so it retries. The fix is an Idempotency-Key header. The server records the first response under that key and replays it for every repeat. Agents write the happy path correctly. They miss the concurrent case, because the naive version stores the response only after the handler finishes. Two simultaneous retries both find an empty cache, and both charge.

Copy-paste prompt: idempotency-key middleware

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.

Two decisions stay with you, and neither is visible in the diff. First, the retention window: a 24-hour TTL means a retry on day two charges again. Match the TTL to the longest retry window of your slowest client, such as an offline mobile queue. Second, Redis is a cache. An eviction or a failover forgets keys, which is why the prompt asks for the unique constraint on orders.idempotency_key. The database refuses the second insert even when Redis has forgotten the first. Test 2 is the one that matters. If it passes with 10 parallel requests, the race is closed, whatever the middleware looks like inside.

How do you paginate an API without dropping or repeating rows?

Offset pagination (?page=3&limit=20) shifts every time a row is inserted while someone pages. Cursor (keyset) pagination fixes that, but agents introduce two quieter bugs. They sort on a non-unique column, so rows that share a created_at are skipped or repeated at the page boundary. They also round-trip the timestamp through a JavaScript Date, which keeps milliseconds while Postgres timestamptz stores microseconds. That produces the same skip on data that looks unique.

Copy-paste prompt: keyset pagination for GET /orders

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 switches off sequential scans (or seeds enough rows) because on a table of 57 rows the Postgres planner rightly prefers a sequential scan, so a bare EXPLAIN assertion would flake, and an agent that sees it flake will weaken it instead of fixing the query.

You do not have to read the SQL to trust the result. Test 1 is a complete walk: if any row is lost or duplicated at any boundary, the set comparison fails. To widen it, turn the fixed 57 rows into a generated property (“for any multiset of timestamps and any page size, the walk returns every row once”), as described in property-based testing with agents. Test 3 guards the performance half of the pattern. Without the composite index, the keyset query is correct but scans the table, and that only shows up in production at scale. For index and query-plan work beyond this endpoint, see SQL optimization patterns.

How do you keep the OpenAPI spec from drifting away from the code?

A hand-written spec drifts, because nothing fails when it goes stale. Generate it from the Zod schemas the handlers already validate against, commit the output, and let CI fail when the committed file differs from a fresh build. @asteasolutions/zod-to-openapi (npm, 9.1.0 on 2026-09-26) builds OpenAPI 3.x documents from registered Zod schemas.

Copy-paste prompt: OpenAPI 3.1 generated from Zod

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.

The git diff --exit-code step is what keeps the spec current. It is more robust than an in-memory comparison test, because it checks the exact file that consumers download. Lint the result with npx @redocly/cli lint openapi.json (Redocly CLI 2.54.3 on 2026-09-26) to catch missing operation IDs and undeclared security. When a route has no schema, the prompt tells the agent to stop, not to invent one. An agent that “fills the gap” writes the hand-maintained spec you are trying to remove.

How do you verify the agent’s API code without reading every line?

Run the service and attack it with its own contract. Schemathesis (PyPI, 4.28.0 on 2026-09-26) reads openapi.json, generates valid and invalid requests for every operation, and checks each response against the spec: server errors, status codes, response schemas, and whether invalid input is rejected.

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

A green Schemathesis run, the concurrency test, and the pagination walk together prove more than a careful read of the handlers. Hand the whole run to the agent, and ask for the result as evidence rather than as a summary.

Copy-paste prompt: produce the API evidence bundle

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.

What the reviewer reads changes as a result. The reviewer reads the openapi.json diff (the contract) and the evidence table, not the middleware. A contract change that removes or narrows a field needs sign-off from the team that consumes the API. A change with no contract diff and green checks needs only the owning team’s approval. The page on the evidence bundle an agent’s pull request must carry turns this into a PR contract with a CI check. Protecting the oracle covers the rule in the last line of the prompt: an agent must not edit the tests that judge it.

How do you open the API pull request through the GitHub MCP server?

When the spec changes, the agent can open the pull request, attach the evidence section, and request review from the consuming team through GitHub’s official MCP server. The remote server at https://api.githubcopilot.com/mcp/ takes a GitHub personal access token in an Authorization header in all three clients. The commands below use a PAT kept in an environment variable, never in a committed file.

Cursor

Add a github server with the URL https://api.githubcopilot.com/mcp/ and an Authorization: Bearer header in ~/.cursor/mcp.json (your user config, outside the repository). The GitHub MCP server guide has the exact JSON.

Claude Code

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

Codex

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

If the agent already has the gh CLI and a shell, gh pr create --body-file evidence.md does the same job with fewer tokens. Use the MCP server when you want the agent to also read CI logs and review comments without shell access.

When agent-written API patterns break in production

Failure modes and how to recover

• The idempotency check races itself. The response is stored after the handler runs, so parallel retries both charge. Recover: find duplicates with SELECT idempotency_key, count(*) FROM orders GROUP BY 1 HAVING count(*) > 1, refund them, add the unique constraint, and require the 10-way parallel test before merging.
• Keys vanish from Redis. An eviction policy such as allkeys-lru removes idempotency entries under memory pressure. Recover: use a separate Redis database or instance with noeviction for idempotency keys, and rely on the database constraint as the backstop.
• Pagination skips rows that look unique. The cursor carries a millisecond Date while the column stores microseconds. Recover: encode the timestamp as text from Postgres, and add microsecond-distinct rows to the walk test.
• OFFSET reappears in a later change. A different agent session “simplifies” the query. Recover: the walk test with a mid-walk insert fails. Keep it in the default test run, not in a slow suite nobody runs.
• The spec goes stale anyway. Someone adds a route without registering its schema, so the generator never sees it. Recover: add a test that lists the Express router’s routes and fails for any route missing from the registry.
• The agent invents a package. Plausible names such as express-idempotent-middleware do not exist on npm (checked 2026-09-26). Recover: run npm view <package> version on every dependency the agent adds, and see dependency verification for the CI gate.
• Error responses leak internals. Generated handlers put the raw database error in details. Recover: return a stable error code and a traceId, log the database error server-side, and add a Schemathesis run to CI so that any 500 fails the build.
• Padding nobody asked for. Asked for “RESTful best practices”, agents add HATEOAS _links envelopes that no client reads. Recover: name the response shape in the prompt, as every prompt on this page does.

Where to go next with API patterns

• Spec-first API development with agents: design the contract, auth, and versioning before the routes on this page exist.
• API test automation: contract and consumer tests that extend the Schemathesis run.
• Node.js and Express recipes: JWT auth, rate limiting, and background jobs on the same stack.
• Serverless development patterns: deploying these APIs to functions and the edge, where idempotency matters even more.
• Reading evidence instead of code: why the reviewer on this page reads the contract and the checks rather than the code.