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 methods, safety, idempotency

Method	Purpose	Safe	Idempotent	Body
GET	Read	yes	yes	no
HEAD	Read headers	yes	yes	no
POST	Create / non-idempotent action	no	no	yes
PUT	Full replace (client sets full state)	no	yes	yes
PATCH	Partial update	no	not inherently	yes
DELETE	Remove	no	yes	maybe

• Idempotent = same request repeated yields same server state (not same response — a repeated DELETE may return 404 the second time; that's fine).
• PUT replaces the entire resource — omitted fields are cleared. If a client can't send full state, use PATCH.