API contract design (frontend ↔ backend)

Contract first

The schema (OpenAPI/GraphQL/tRPC types) is the source of truth, generated into the client. Hand-typed interfaces that "roughly match" the API rot within weeks.

Resource modeling

• Nouns not verbs: POST /orders, not POST /createOrder.
• Relationships in paths: GET /users/:id/orders?status=paid.
• One resource, one shape. If the mobile app needs less, that's field selection/projection — not a second endpoint with mystery fields.

Pagination: offset is a trap

• Offset (page=3) breaks under inserts/deletes and degrades on deep pages.
• Default to cursor pagination: ?cursor=<opaque>&limit=50, response carries nextCursor. Opaque cursors also prevent clients from hand-crafting queries.
• Every list response states its shape explicitly:

{ "items": [...], "nextCursor": "eyJpZCI6...", "hasMore": true }

Errors: one envelope, machine-readable

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "email is not a valid address",
    "details": [{ "field": "email", "rule": "format" }],
    "requestId": "req_9f2c"
  }
}

• HTTP status classes stay correct (4xx client, 5xx server) but the code string is what clients branch on — never parse message.
• requestId on every error; it's the join key to server logs when a user reports "it didn't work".

Idempotency & retries

• Non-GET from clients that retry (network flake, double-click) carries Idempotency-Key: <uuid>; server dedupes.
• Client retries: exponential backoff + jitter, only on idempotent requests or with a key; timeouts on everything.

Versioning

• Version at the URL or header (/v1/), never at field names (nameV2).
• Additive changes only within a version; breaking changes bump.
• Deprecation is a process: announce → dual-write window → remove. Clients see a Deprecation/Sunset header before the break.

Auth & multi-tenancy

• Every endpoint states its auth requirement in the schema; the client's generated types force the token flow.
• Tenant scoping is server-side on every query — "my orders" means where userId = caller, enforced once in the data layer, not per endpoint.

Definition of done (agent checklist)

• Schema is generated/consumed, not hand-mirrored
• Lists: cursor pagination + explicit envelope
• Errors: code + details + requestId, statuses correct
• Mutations: idempotency keys where retries possible
• Breaking changes versioned; deprecation headers wired