microclaw/api-design

API Design

Aim for boring, predictable APIs. Consistency beats cleverness — a caller should be able to guess the next endpoint.

Resources & methods

• Name resources as plural nouns: /users, /users/{id}, /users/{id}/orders.
• Map methods to intent: GET (read, safe), POST (create/action), PUT (full replace), PATCH (partial update), DELETE (remove). GET/PUT/DELETE should be idempotent.
• Avoid verbs in paths (/createUser ✗). For non-CRUD actions, POST a sub-resource (POST /orders/{id}/refund).

Status codes (use the right one)

• 200 OK, 201 Created (+ Location), 202 Accepted (async), 204 No Content.
• 400 bad input, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict, 422 validation failed, 429 rate-limited (+ Retry-After).
• 500 server error (never leak internals), 503 unavailable.

Consistent shapes

// Error envelope — same shape everywhere
{ "error": { "code": "invalid_amount", "message": "amount must be > 0", "field": "amount" } }

// List with pagination
{ "data": [ ... ], "next_cursor": "abc123", "has_more": true }

Guidance

• Prefer cursor pagination over offset for large/changing sets.
• Version explicitly (/v1/... or a header); never break v1 callers silently.
• Use ISO 8601 timestamps, consistent snake_case or camelCase (pick one), and stable IDs.
• Validate input and return 4xx with a precise message; reserve 5xx for real server faults.
• Make writes idempotent where possible (idempotency keys for POST that creates money/orders).
• Document each endpoint: method, path, params, example request/response, error cases.