API review checklist

Last updated Jun 14, 2026

This checklist is what the API Council walks during gate 1 (spec draft review) and gate 2 (Council weekly forum). It is also the canonical reviewer cheat-sheet on every spec PR.

Items are grouped by concern. Each item references the principle, primitive, or runbook it enforces.

Consistency (shape, naming, structure)

1. URL is resource-oriented, not RPC-verb-oriented. Verbs appear only as terminal path segments for actions that genuinely cannot be expressed as state.
2. Path uses snake_case (e.g. /v1/share_classes, not /v1/shareClasses).
3. Resource name is plural (/v1/entities, not /v1/entity).
4. Sub-resource paths nest correctly (/v1/entities/{id}/grants/{grant_id}, not /v1/grants?entity_id=... for an owned sub-resource).
5. Typed ID prefix declared via x-matter-id-prefix. Lives in packages/resource-ids/src/index.ts.
6. JSON shapes use snake_case consistently.
7. List response envelope is { object: "list", data, has_more, url, next_cursor? } — same shape across every list endpoint.
8. Cursor pagination with limit (default 10, max 100), starting_after, ending_before. Never offset-based.
9. Custom-action verb (if any) reads naturally as an imperative — dissolve, revoke, accelerate. Not setter-like (setStatus).
10. Idempotent verbs (GET, PUT, DELETE) are idempotent by HTTP definition. POST mutations require Idempotency-Key.

Semantics (state, transitions, contracts)

11. State machine (if applicable) is exhaustively typed. No string-valued status fields.
12. Invalid state transitions return 409 with code: state_transition_invalid.
13. Pre-conditions documented in the operation description (e.g. "Requires entity in active state").
14. Authorising Resolution required where applicable (authorizing_resolution_id is mandatory for cap-table mutations).
15. Optimistic concurrency version column on TOCTOU-exposed resources. Conflicting writes return 409.
16. Composite atomic flows are sagas with typed compensation. Documented in the spec as such.
17. Dry-run supported on every mutation via ?dry_run=true. Returns a structured ExecutionPlan and the would-be resource.
18. Async-by-default for any operation with provider I/O. Returns 202 + Request.
19. Synchronous reads route through the consistency middleware. Operation declares x-matter-consistency: strict | eventual or accepts the operation-class default.
20. Webhook event declared for every state transition. Event type follows the <resource>.<verb> convention.

Error handling

21. Error responses are application/problem+json (RFC 7807). Never application/json for errors.
22. code is kebab-case, prefixed by family (auth_, scope_, validation_, state_, not_found_, op_, infra_).
23. type points to an existing docs page at apps/docs/content/docs/errors/<code>.mdx. CI gate enforces.
24. detail is actionable. Includes field path, value seen, expected shape, "did you mean" where applicable.
25. instance is a per-request URN (urn:matter:request:<request_id>).
26. No PII in any error field — redact() is called at construction.
27. Cross-tenant lookups return 404 (not_found_in_mode or not_found_resource), never 403. Do not leak existence.

Security

28. x-matter-auth declared if the operation deviates from the default Bearer contract (e.g., requires fresh OAuth, requires signing session, requires step-up).
29. x-matter-mcp declared with min_tier, read_only, idempotent, workflow, and (if sensitive) never_expose: true.
30. Scope policy derived from x-matter-mcp.min_tier + x-matter-auth via codegen.
31. Rate limit declared via x-matter-rate-limit (per-tier).
32. PII fields marked x-matter-pii: true.
33. Encrypted fields marked x-matter-encrypted: true (mandatory for Highly Restricted; optional for Restricted).
34. Classification declared via x-matter-classification: public | confidential | restricted | highly_restricted.
35. Audit-on-read triggers automatically for Highly Restricted fields. No manual wiring required.
36. Webhook payload does not contain Highly Restricted fields in fat or thin form (per data classification rules).
37. SSRF defense if the endpoint accepts a customer-supplied URL — validated against the allowlist.
38. Prompt-injection defense if the endpoint feeds untrusted input into an AI call (input length cap, structural validation, output schema validation, sandboxed prompt template, no tool-calling).

Performance

39. SLO class declared via x-matter-slo.class (one of nine classes).
40. SLO override declared if the operation needs tighter / looser budget than its class default.
41. Cost budget declared via x-matter-cost-budget.
42. Cache layer declared via x-matter-cache-layer (none | request | redis | edge | snapshot).
43. Cache target declared via x-matter-cache-target for cached operations.
44. Expand depth declared via x-matter-expand-max-depth (default 4).
45. N+1 audit — for expand fields, hydrator is batched. No per-row lookup.
46. Consistency contract explicit per operation.

Async and webhooks

47. 202 path returns Request resource with typed status and next_actions[].
48. Saga for any composite atomic flow. Typed compensation handlers. TLA+ spec for high-stakes sagas.
49. Webhook events emitted in same transaction as resource + audit write.
50. Event versioning — every Event carries apiVersion. Transformers convert to older shapes on delivery.
51. 30-day replay window — re-deliverable via POST /v1/events/{id}/redeliver within 30 days.

DX (developer experience)

52. x-matter-explainer on every non-trivial property. Long-form educational context, not the one-liner that's in description.
53. Operation summary ≤ 80 chars; reads as a sentence ("Create an entity").
54. Operation description ≥ 80 chars but ≤ 600; states what + how + when. No competitor comparisons.
55. Examples present in request body and 2xx + 4xx response.
56. Code samples auto-generated by apps/docs/scripts/generate-code-samples.ts.
57. MCP tool description quality bar — lifecycle phase, min tier, one-line example payload in the description.
58. SDK example committed alongside the SDK source for the canonical use case.

Maturity and deprecation

59. x-matter-maturity declared. Default preview for new endpoints.
60. Deprecation plan if the endpoint replaces an existing one. Sunset date set; migration guide drafted.
61. Deprecation + Sunset + Link headers automatic on Deprecated endpoints (no handler code).
62. Personalised emails to active users of deprecated endpoints (P11.33).
63. Sunset behaviour — endpoint returns 410 Gone with code: op_endpoint_sunset + migration guide link.

Internationalisation

64. Error messages localised via the i18n codegen (x-matter-i18n-key on the error code).
65. Multi-currency fields carry an explicit currency (ISO 4217). Customer-supplied value validated.
66. Multi-language Accept-Language honored where the response is customer-facing.
67. Date handling uses ISO 8601 UTC in storage; locale-rendered in response with Matter-Locale header.
68. Address handling uses CLDR-compliant address structure where applicable.
69. Unicode normalisation (NFC) on every text-equality boundary (lookup, search, deterministic IDs).

Operational

70. Runbook linked from any high-stakes endpoint.
71. Alert typed in packages/observability/src/alerts.ts if the endpoint has a unique failure mode.
72. Cost budget enforced in CI under load test.
73. Tenant-isolation test added to apps/api/__tests__/tenant-isolation/<phase>/.
74. Per-mode parity — live + sandbox + test all covered in integration test.
75. Cross-version compat test — current minor + previous minor both validated.
76. Mock-vs-real parity gate — before retiring the catch-all mock for this operation, real handler response is shape-compatible with the mock's.

Documentation

77. Spec PR + docs PR can be the same PR (auto-generation from spec). Hand-written narrative goes in apps/docs/content/docs/concepts/ or apps/docs/content/docs/cookbook/ as appropriate.
78. Changelog entry auto-generated via oasdiff (P11.15).
79. Breaking changes blocked within minor — oasdiff CI fails if a breaking change is introduced without bumping the minor.

Sign-off

80. API Council approval recorded in council minutes for non-trivial endpoints. Bounded-context owner approval required for any endpoint that crosses or modifies the context's invariants.

---

This list is exhaustive and intentional. If an item feels heavy, it is because the platform-level cost of getting that item wrong is heavy. Reviewers walking this list are doing the work of preventing 12 future engineers from each independently rediscovering the same lesson.

See also

• API Council — the forum that walks this list.
• API design philosophy — the ten principles this list enforces.
• Bounded contexts — context owners review changes that touch their context.