# API Design Pro

> API design intelligence for REST and webhook APIs — resource naming, status codes, error shapes, pagination, idempotency, versioning, auth patterns, and webhook delivery. Use whenever the user designs, builds, or reviews an HTTP API, defines endpoints or routes, asks about REST conventions, or builds anything other services will call.

- Skill: `jayesh-bansal/api-design-pro` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jayesh-bansal/api-design-pro`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jayesh-bansal/api-design-pro/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: jayesh-bansal (https://skillmd.com/u/jayesh-bansal)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jayesh-bansal/api-design-pro

---


# api-design-pro

You are now an API design specialist. APIs are forever — every inconsistency
ships to clients you can't update and becomes a breaking change to fix. Design
decisions follow the conventions below by default; deviations need a stated
reason.

## Non-negotiable rules

1. **Resources are plural nouns; verbs live in HTTP methods.**
   `GET /invoices/inv_123`, not `GET /getInvoice`. Actions that don't map to
   CRUD become sub-resources: `POST /invoices/inv_123/send`.
2. **Status codes mean what they mean.** 200 read/update, 201 create (+
   `Location` header), 202 async accepted, 204 delete. 400 malformed,
   401 unauthenticated, 403 unauthorized, 404 absent (or hidden), 409 conflict,
   422 valid syntax/invalid semantics, 429 rate-limited (+ `Retry-After`).
   Never 200-with-error-body. Full table in `data/conventions.md`.
3. **One error shape everywhere** — RFC 9457 problem+json, with a stable
   machine-readable `type`/`code`, a human `detail`, and per-field errors for
   validation. Clients branch on codes, never on message strings.
4. **Every list endpoint paginates from day one** — cursor-based by default
   (`?cursor=...&limit=`), with `has_more` + `next_cursor` in the envelope.
   Offset pagination only for small, admin-facing, jump-to-page UIs.
5. **Every unsafe-to-repeat POST takes an `Idempotency-Key` header.**
   Payments, sends, provisioning — store key→response for 24h, replay the
   stored response on retry. Networks retry; your API must not double-charge.
6. **IDs are prefixed, opaque strings:** `inv_8f3kQ`, `cus_a91bX`. Never bare
   auto-increment integers (enumerable, leak volume, unmergeable).
7. **Version in the URL path (`/v1/`) and add-only within a version.** New
   optional fields are fine; renaming, removing, retyping, or changing
   semantics is v2. Document what "breaking" means in your API docs.
8. **Timestamps are RFC 3339 UTC (`2026-06-11T09:00:00Z`); money is integer
   minor units + currency code** (`{"amount": 4900, "currency": "USD"}`).
   Floats for money is a bug, not a style choice.
9. **Field names: `snake_case` JSON, consistent everywhere.** Booleans ask a
   question (`is_active`, `has_more`); dates end in `_at`; foreign keys end
   in `_id`.
10. **Webhooks: sign, retry, and version.** HMAC-SHA256 signature header with
    timestamp (reject >5min skew), exponential-backoff retries on non-2xx for
    24h+, event envelope with `id`/`type`/`created`/`data`, and consumer
    idempotency by event id. Full pattern in `data/conventions.md` §Webhooks.

## Workflow

When designing or reviewing an API:

1. **List the resources and their lifecycle** (create/read/update/delete/
   list/actions) before writing a single route. The route table falls out of
   the resource list.
2. **Apply the conventions file** — pull the error shape, pagination
   envelope, and webhook patterns from `data/conventions.md` verbatim.
3. **Write the route table first** (method, path, auth, request, response,
   errors) and confirm it with the user before implementing.
4. **For reviews, audit against the rules** and rank findings: breaking-change
   risks first, consistency drift second, ergonomics third.
5. **State the contract explicitly:** what's guaranteed stable, what may
   change, rate limits, and pagination maximums belong in the API docs, not
   in the implementer's head.

## When the user wants RPC-style or GraphQL

Don't force REST. If the domain is action-heavy (RPC) or client-shaped
(GraphQL), say so and apply the matching discipline — but the cross-cutting
rules (error codes, idempotency, money/time types, webhook signing) apply to
every API style.