API contract

The contract is the promise. Write it down before the implementation and change it additively.

Per endpoint, document

### POST /v1/orders
Auth: session (role: staff)       Idempotent: yes (Idempotency-Key header)
Request:  { items: [{ sku: string, qty: int>0 }], note?: string<=500 }
200:      { id: string, status: "pending"|"paid", total: { amount: int (minor units), currency: "USD" } }
400 ERR_VALIDATION · 401 ERR_AUTH · 403 ERR_FORBIDDEN · 409 ERR_CONFLICT · 429 ERR_RATE_LIMIT
Notes: total is computed by the server; clients never send it.

Shape rules

• JSON, camelCase (or one convention, everywhere).
• IDs are opaque strings. Timestamps are ISO-8601 UTC. Money is integer minor units + currency.
• Enums are strings, documented; clients must tolerate unknown values.
• Nullable vs optional is explicit.
• Never return secrets, tokens or internal fields; serialize through an allowlist.

Errors

One shape for every error (see error-codes-registry):

{ "error": { "code": "ERR_VALIDATION", "message": "qty must be > 0", "details": { "field": "items[0].qty" } } }

Correct status codes: 400 validation, 401 not signed in, 403 not allowed, 404 not found (also for "exists but not yours"), 409 conflict, 422 if you separate semantic errors, 429 rate limit, 5xx only for server faults.

Lists

Cursor pagination (?cursor=…&limit=… → { items, nextCursor }), a maximum limit, stable sort order, filters as query params.

Writes

• Idempotency keys for anything that creates or charges.
• Optimistic concurrency (ETag / If-Match or a version field) for edits.
• Server owns derived values (totals, permissions, timestamps).

Changing a contract

Change	Safe?	How
Add optional field / new endpoint	✅ additive	ship server first
Add enum value	⚠️	only if clients tolerate unknowns
Make optional → required (request)	❌ breaking	new version or default server-side
Rename / remove / retype a field	❌ breaking	add new field → migrate clients → deprecate → remove after {{DEPRECATION_WINDOW}}

Rollout order: server accepts both shapes → clients move → server drops the old. Find every caller before removing anything (the scout agent's route-impact brief).

Verify

• Contract tests: each documented status and shape is asserted.
• Schema (OpenAPI / zod) is the single source; types are generated from it.

Customize for your project

{{API_CONTRACT}} (e.g. docs/api-contract.md or openapi.yaml), {{API_STYLE}} (REST, RPC, GraphQL), auth scheme, {{DEPRECATION_WINDOW}}.