API Development Patterns

Your POST /orders endpoint double-charges customers when the mobile client retries on a flaky connection. Your cursor pagination silently drops rows when two records share a created_at. And the OpenAPI spec you hand-wrote drifted from the code three sprints ago, so the generated client is lying to every frontend dev who trusts it. These are the API bugs that survive code review and surface in production — and they’re exactly where an AI agent earns its keep, because the fix is a known pattern, not a creative act.

This recipe shows the prompts that turn “the AI scaffolded a route” into “the route is idempotent, paginated correctly, and documented from the source of truth.” We use Express + TypeScript + Zod as the anchor stack, but the prompts port cleanly to Fastify, NestJS, or Next.js Route Handlers.

What You’ll Walk Away With

• A paste-ready prompt that generates idempotency-key middleware so client retries never double-charge.
• A cursor-pagination prompt with a stable composite sort that doesn’t drop rows.
• An OpenAPI-3.1-from-handlers prompt that derives the spec from your Zod schemas, so it can’t drift.
• The three-tool workflow for scaffolding an endpoint (Cursor, Claude Code, Codex) and when each shines.
• A “When This Breaks” checklist for the failure modes these AI-generated patterns hit in production.

Scaffolding an endpoint across the three tools

The first move on any new endpoint is the same: hand the agent your existing route conventions and let it match them. Where the tools differ is how you drive that — inline in the editor, in the terminal, or non-interactively in CI.

Cursor

Open the router file so it’s in context, then open Agent mode (Cmd/Ctrl + I) and reference the file explicitly:

Using the conventions in @src/routes/users.ts, add a POST /orders route to @src/routes/orders.ts. Validate the body with a Zod schema (items: array of {sku, qty}, idempotencyKey: uuid), return 201 with the created order, and 409 on a duplicate idempotency key. Wire it into the existing error-handling middleware — do not invent new error classes.

Agent mode edits the file in place and shows a diff per file. Use Checkpoints before accepting so you can roll back the whole change if the validation shape is wrong.

Claude Code

From the repo root, give Claude Code the same instruction and let it read the conventions itself:

claude "Read src/routes/users.ts for our route conventions, then add a POST /orders \
route in src/routes/orders.ts. Validate the body with Zod (items, idempotencyKey:uuid), \
return 201 on success and 409 on duplicate key, and reuse the existing error middleware."

Claude Code uses its Read and Edit tools to match your patterns. Add --permission-mode plan first if you want it to propose the change before touching files.

Codex

Use codex exec for a scripted, non-interactive run — ideal when you want the change to land as a single reviewable commit:

codex exec --ask-for-approval on-request \
"Add a POST /orders route in src/routes/orders.ts following the conventions in \
src/routes/users.ts. Zod-validate the body (items, idempotencyKey), return 201/409, \
and reuse the existing error middleware."

For interactive work, drop the exec and run codex in the TUI. Codex Cloud can run the same task in an isolated worktree and open a PR — useful when the endpoint touches migrations you want reviewed in isolation.

Idempotent endpoints: the double-charge fix

A retried POST is the classic distributed-systems trap. The fix is an idempotency-key middleware that records the first response and replays it for any repeat of the same key. This is mechanical enough that the AI gets it right — if you tell it where to store the key and how long to keep it.

Tip

Copy-paste prompt — idempotency-key middleware:

Write Express middleware idempotency() in TypeScript that:

• reads the Idempotency-Key header (reject with 400 if missing on POST/PATCH)
• on first request for a key, runs the handler, then stores {statusCode, body} in Redis under idem:{key} with a 24h TTL
• on a repeat key, returns the stored response with header Idempotent-Replay: true instead of re-running the handler
• handles the in-flight race: if a request with the same key is already processing, return 409 with Retry-After: 1
• uses the ioredis client already exported from src/lib/redis.ts

Show the middleware plus a Vitest test that fires the same request twice and asserts the second is a replay, not a second insert.

When the AI hands this back, audit two things before you trust it. First, the in-flight lock: a naive version stores the response only after the handler finishes, so two simultaneous retries both miss the cache and both charge. The replay entry must be claimed (e.g. SET idem:{key} "processing" NX) before the handler runs. Second, the TTL vs. business window: a 24h TTL means a retry on day two double-charges anyway. Ask the AI to make the window explicit and matched to your client’s retry policy.

Cursor pagination that doesn’t drop rows

Offset pagination (?page=3&limit=20) is fine for an admin table but breaks under writes: insert a row while a user pages and everything shifts. Cursor pagination is the production answer, and the bug AI models reliably introduce is sorting on a non-unique column. If two orders share a created_at, a cursor on created_at alone will skip or repeat rows at the page boundary.

Tip

Copy-paste prompt — keyset cursor pagination:

Implement cursor-based pagination for GET /orders in Express + TypeScript over a Postgres table orders(id uuid pk, created_at timestamptz, ...). Requirements:

• sort by (created_at DESC, id DESC) — a composite key so the cursor is always unique
• the cursor is an opaque base64 of {created_at, id}; decode it server-side and reject a malformed cursor with 400
• the SQL must use the keyset predicate (created_at, id) < ($1, $2) with LIMIT $3 + 1 to detect hasNextPage, NOT OFFSET
• response shape: { data: [...], pageInfo: { nextCursor, hasNextPage } }
• parameterize every value — no string interpolation into SQL

Include a test that inserts two rows with an identical created_at and proves neither is dropped or duplicated across a page boundary.

The tell that the AI did this right is the composite predicate. WHERE created_at < $1 is wrong; WHERE (created_at, id) < ($1, $2) is right. If you see OFFSET anywhere in the generated query, reject it — that’s the bug you came here to avoid.

OpenAPI from the source of truth

Hand-maintained OpenAPI drifts. The durable fix is to derive the spec from the same Zod schemas your handlers already validate against, so the contract and the runtime can’t disagree. Libraries like @asteasolutions/zod-to-openapi make this a generation step rather than a parallel document.

Tip

Copy-paste prompt — generate OpenAPI 3.1 from Zod:

We validate every route with Zod schemas defined alongside the handlers in src/routes/. Wire up @asteasolutions/zod-to-openapi so we generate an OpenAPI 3.1 document from those schemas:

• register each route’s request and response schemas with the OpenAPIRegistry
• emit openapi.json via a script npm run openapi:gen
• add a Vitest test that fails CI if openapi.json is stale relative to the registered schemas (regenerate in-memory and deep-compare)
• include security schemes for our Bearer JWT auth

Do not hand-write paths — derive everything from the registered Zod schemas so the spec can’t drift from the code.

The CI staleness check is the part that makes this stick. Without it, the spec regenerates only when someone remembers, and you’re back to drift. With it, a schema change that doesn’t regenerate the doc fails the build.

Note

Once the spec is generated, GitHub’s official remote MCP server lets the agent open the PR, attach the regenerated openapi.json, and link the diff — useful when the contract change needs a frontend team’s sign-off. It’s a hosted HTTP endpoint, so there’s nothing to install: add it once with claude mcp add --transport http github https://api.githubcopilot.com/mcp/ (or the equivalent in Cursor’s and Codex’s MCP config) and the workflow is identical across all three tools.

When This Breaks

Caution

Failure modes these AI-generated patterns hit in production:

• The idempotency cache races itself. The model stores the response after the handler returns, so two simultaneous retries both miss. Demand the claim-before-run lock and a test that fires concurrent requests.
• Cursor pagination on a non-unique column. If the generated query sorts on created_at alone, it drops rows at page boundaries. Insist on the composite (created_at, id) keyset and reject any OFFSET.
• OpenAPI hand-written “to save time.” The AI may generate paths by hand instead of from your schemas, recreating the drift problem. Verify it registers schemas and that the CI staleness test exists.
• Over-engineered HATEOAS. Asked for “RESTful best practices,” models pad responses with _links envelopes no client consumes. Only add hypermedia if a real consumer reads it.
• Invented middleware or packages. Watch for imports of plausible-but-nonexistent packages (e.g. a made-up express-idempotent-middleware). Run npm view <pkg> version on anything you didn’t already have in package.json — if it 404s or is flagged deprecated, don’t wire it in.
• Localized error messages leaking internals. Generated error handlers sometimes echo the raw DB error in details. Strip stack traces and SQL from anything a client sees; log them server-side with a traceId instead.

What’s Next

• Database Development Patterns — the query-optimization and zero-downtime-migration prompts behind these endpoints.
• Serverless patterns for deploying these APIs to the edge.