---
name: REST API design
description: Design a new HTTP endpoint with idempotency, error shape, and pagination defaults already correct
tags: [api, design, team]
author: fastpace
---

Design the requested endpoint. Produce: route, method, request shape, response shape, error shape, idempotency story, pagination story.

**Route + method.** Resource-noun URLs (`POST /charges`), not verb-URLs (`POST /createCharge`). Use the team's existing version prefix (check `packages/api` or `src/routes` for the convention).

**Request shape.** JSON body, snake_case keys (or match the team's convention — check three existing endpoints first). Validate every field at the boundary. List required vs optional explicitly.

**Response shape.** Wrap successes in `{ data: … }`; never return a raw array or scalar at the top level (limits future evolvability). Include a `request_id` field for client-side correlation if the team's existing endpoints do.

**Error shape.** Use the team's existing error envelope. If none exists, propose one: `{ error: { code: string, message: string, request_id: string } }`. List which HTTP status codes you'll emit and why.

**Idempotency.** Mutating endpoints accept an `Idempotency-Key` header. Reads are idempotent by definition. Document the retention window for stored idempotency keys.

**Pagination.** Defaults: cursor-based (`?cursor=…&limit=50`). Page-number pagination breaks under concurrent inserts; only use it if every existing endpoint already does.

If any decision conflicts with the team's existing API conventions, name the conflict explicitly and propose the lesser-disruption option.