Api Design

API Design

> Design REST APIs that are predictable, evolvable, and safe. Principles are firm; the numbers and snippets below are starting points — fit them to the project.

Principles (firm)

1. URLs are plural, kebab-case nouns. No verbs in paths. /users/:id, /users/:id/orders. Verbs only for non-CRUD actions (/orders/:id/cancel).
2. HTTP method = semantics. GET safe, PUT/DELETE idempotent, POST not. Don't return 200 {success:false} — use the real status.
3. Errors are typed. Body: { error: { code, message, details? } }. The client switches on code, not status alone. Never leak stack traces or SQL.
4. List endpoints paginate. Always bounded; never return unbounded sets.
5. Validate every inbound payload at the boundary (Zod / class-validator / Pydantic). Reject 422 on semantic failure, 400 on malformed.
6. Authn + authz on every endpoint — or mark it explicitly public. Ownership-check resources (a user reads only their own).
7. Version only on breaking change. Add fields freely; rename/remove/retype → new version.

Reference (adjust to context)

Status codes: 200/201/204 success · 400/401/403/404/409/422/429 client · 500/502/503 server (send Retry-After on 503/429).

Pagination — pick per use case:

| Need | Use | |------|-----| | Jump to page N, small/admin datasets | Offset | | Feeds, infinite scroll, large/concurrent data, public APIs | Cursor |

Filtering/sorting: query params — ?status=active&sort=-created_at&fields=id,name.

Auth: user sessions → Authorization: Bearer ; service-to-service → API key header. No custom session headers (invisible to gateways/scanners).

Rate limiting: tier by caller, stricter on auth endpoints, return X-RateLimit-* + Retry-After. Example tiers: anon 30/min, authed 100/min, premium 1000/min — set real values from traffic, don't copy these.

Auth contract (any stack, when the API issues tokens)

• Two checks per protected route: authentication (token valid) AND authorization (identity allowed this resource). A valid token is not permission; never merge them into one guard.
• Refresh rotation: each refresh issues new access + refresh tokens and invalidates the old refresh immediately. Reuse of an invalidated token → revoke the whole family, force re-login.
• Logout revokes server-side (denylist or family rotation) — clearing the client cookie leaves the token alive.
• Expiry bounds: access ≤ 15 min; refresh has an explicit absolute max (7–30 days) plus inactivity expiry. "Never expires" is invalid.
• OAuth code flow uses PKCE: random code_verifier ≥ 43 chars, only its SHA-256 challenge in the authorize request, verifier only in the token exchange, never stored after.
• No user enumeration: "user not found" and "wrong password" return the identical response. Log server-side with context; never expose stack traces or internal IDs.
• Rate-limit login, refresh, and password reset — absence is a security gap, not a missing feature.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pixelcrafts-app
• Source: pixelcrafts-app/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.