design-principles

Design Principles

Apply these when designing or reviewing anything with a contract or a trust boundary in MCP Runtime: REST/JSON-RPC APIs, CRD shapes (api/v1alpha1), CLI flags, operator reconciliation, the gateway pipeline, Sentinel services, and MCP tool surfaces. Prefer these over ad-hoc choices; when two are in tension, make the tradeoff explicit (see Make tradeoffs explicit).

One-line north star:

Good design makes the right thing easy, the wrong thing hard, and future change less painful.

API design (the 12)

1. RESTful resource naming — nouns, not verbs. GET /users/{id}, not GET /getUser.
2. Simple, predictable URLs — guessable paths. /users/{id}/orders, not /fetchAllOrdersForUser.
3. Correct HTTP methods — GET read, POST create, PUT full update, PATCH partial, DELETE delete.
4. Proper status codes — 200/201, 400/401/403/404/409, 500. Don't return 200 with an error body.
5. Consistent request/response shape — predictable JSON envelope ({ "data": …, "error": … }).
6. Clear, coded errors — { "code": "INVALID_EMAIL", "message": "…", "field": "email" }, never just "failed".
7. Filtering, sorting, pagination on list APIs — ?status=active&sort=created_at&page=1&limit=20. Never return everything.
8. Don't abuse query params for identity — prefer nested paths (/users/123/orders) over ?user_id=123 for core relationships.
9. Version your APIs — /api/v1/… so breaking changes don't break old clients.
10. Clear actions for non-CRUD — POST /orders/{id}/cancel, POST /payments/{id}/retry as explicit sub-resources.
11. Model meaningful state transitions — CREATED → PAID → SHIPPED → DELIVERED; reject invalid jumps.
12. Security from the start — authN (who are you), authZ (what may you do), rate limiting, input validation, no sensitive-data leaks.

API design is about resources, behavior, state, errors, security, and future compatibility — not just endpoints.

System / generic design principles