loom-api-design

# API Design ## Overview Design intuitive, consistent, evolvable API contracts across REST, GraphQL, and gRPC. Get the resource model, HTTP semantics, error envelope, pagination, and versioning right up front — they are the hardest things to change once clients depend on them. ## Design Workflow 1. Model resources and relationships before URLs; name the nouns, then map operations onto them. 2. Pick the paradigm: REST (resource CRUD, caching, broad tooling), GraphQL (client-shaped reads, aggregation, mobile), gRPC (internal, low-latency, streaming, strong contracts). 3. Lock the **error envelope**, **pagination shape**, and **versioning policy** once — reuse everywhere. 4. Design for change: additive evolution, tolerant readers, deprecation windows. 5. Write the spec (OpenAPI/SDL/proto) as the source of truth; generate clients/servers from it. ## REST ### Resource & URL conventions - Nouns, plural collections: `/users`, `/users/{id}`, `/users/{id}/orders`. Never verbs in paths (`/getUsers` is wrong — the method is the verb). - Pick one case (`snake_case` or `camelCase`) and keep it identical across paths, query params, and bodies. - Keep nesting shallow (≤2 levels); deep hierarchies couple resources. Prefer `/orders?user_id=` over `/users/{id}/orders/{oid}/items/...`. - Sub-resource actions that aren't CRUD: model as a resource (`POST /orders/{id}/refunds`) rather than an RPC verb (`POST /orders/{id}/refund`) when the action produces a trackable entity. ### HTTP method...