API design philosophy

Last updated Jun 14, 2026

Matter's API is the product. The dashboard, the MCP server, the SDKs, the CLI — all are windows onto it. That framing forces a design discipline: every API decision is consumed not just by SDK developers but by every other surface and every customer integration for years.

These ten principles govern that discipline. They are evaluated at the API Council before any new endpoint is implemented, and they appear on the API review checklist. Code reviewers reject changes that violate them.

1. Resource-oriented, not RPC-oriented

Every endpoint mutates or reads a resource. The URL identifies the thing, not the action.

Good:

POST /v1/entities
POST /v1/entities/{id}/grants
GET  /v1/entities/{id}/cap_table

Verbs appear only as terminal path segments for actions that genuinely cannot be expressed as state transitions on the resource — the cases where the action carries side effects beyond the resource itself, or where two different actions produce indistinguishable resource states.

POST /v1/entities/{id}/dissolve         # composite atomic flow
POST /v1/entities/{id}/grants/{gid}/exercise   # legal event with cap-table cascade
POST /v1/entities/{id}/formation_packet # Day-0 composite saga
POST /v1/rounds/{id}/close_package      # Series A close composite

What we do not do:

POST /v1/createEntity                # RPC verb
POST /v1/api/EntityService.Create    # RPC namespace
POST /v1/entities/{id}/setName       # setter as RPC verb

The terminal-verb convention is documented in the OpenAPI spec; new operations are reviewed against it.

2. Intent over instruction

Customers declare what they want; the platform resolves how.

POST /v1/intents
{
  "kind": "form_entity",
  "jurisdiction": "DE",
  "entity_type": "c_corp",
  "founders": [...],
  "initial_equity": { "authorised_shares": 10_000_000, "par_value": "0.0001" }
}

The Intent Resolver consumes @repo/jurisdictions plus the customer's prior preferences plus the relevant explainer-defaults, and emits a typed ExecutionPlan. The customer never has to know that Delaware requires a registered agent before the SOS will accept the certificate, that Form 966 is filed after dissolution not before, that the 83(b) election window is 30 days from grant.

Intent endpoints carry ?dry_run=true and return the execution plan without mutating state. Customers preview, then execute.

3. Async-by-default, sync-where-trivial

Anything with provider I/O is async. The 202 returns a Request resource with a typed status (pending / running / succeeded / failed) and webhook events fire on transitions.

Anything pure — cached reads, math, listing — is sync.

Customers explicitly request the consistency contract via ?consistency=strict (route to primary) or default to eventual (route through replicas + cache, with X-Matter-Read-Lag-Window advertising the worst case).

4. Documents as data

Every legal artefact is both:

• a rendered PDF (Document.pdf_url), human-readable, customer-signable, regulator-acceptable;
• a structured JSON object (Document.fields), queryable, versionable, diffable, programmable.

A customer can GET /v1/documents/{id} and get the JSON. They can GET /v1/documents/{id}/render and get the PDF. Both views are kept in sync by the document service.

Versioning is append-only: DocumentVersion rows accumulate; Document.current_version_id advances. Customers can diff two versions.

5. Entity as object

A legal entity is a first-class programmable object. It has:

• Properties — legal_name, jurisdiction, entity_type, status.
• Methods (as URL actions) — submit, dissolve, qualify, convert.
• State (machine-bounded) — draft → submitted → registered → active → dissolving → dissolved.
• Lifecycle events (webhooks) — entity.state_changed, entity.formation_packet.completed, etc.
• Computed views — cap_table, compliance.

This framing is sacred. The lifecycle IA (Create / Manage / Exit) is the dominant structural framing of the product, the docs, the MCP catalog, and the agent-token DSL. It is never flattened.

6. Idempotent by default

Every mutation accepts an Idempotency-Key header. The platform records the (key, token, body-hash) tuple for 24 hours; replays return the original response with Matter-Idempotency-Replayed: true.

For async (202) replays, the original Request body is returned with Matter-Idempotency-Async: true. The webhook stream is not re-fired — clients rely on the Request resource and resubscribe to events if needed.

SDKs auto-mint idempotency keys on every mutation. Customers opt out (rare); they do not opt in.

7. Explicit over implicit

Every load-bearing fact in a request is derived from explicit input, never inferred:

• Mode (live / sandbox / test) is derived from the token prefix; never trusted from a header or body.
• API version (Matter-Version) is required and pinned at token creation; explicit override per request via header.
• Region is the token's pinned region; never inferred from IP.
• Consistency (strict vs eventual) defaults to the operation's class default; explicit override per request.
• Expand depth defaults to the operation's x-matter-expand-max-depth; explicit per request via ?expand[]=.

Inference is a source of bugs and security issues; we refuse it.

8. Errors are useful

Every error is RFC 7807. Every error has a kebab-case code machine-readable to programs. Every error carries title (human summary), detail (actionable, with field path + value seen + "did you mean" suggestion when applicable), instance (per-request URN), and type (URL to a docs page).

The codes belong to six families: auth_*, scope_*, validation_*, state_*, not_found_*, op_*, infra_*. The taxonomy is documented; the docs pages exist (CI gate); the quality of detail is reviewed by the API Council.

9. Backwards compatibility is sacred

Within a minor version (date-pinned, e.g. Matter-Version: 2026-05-01), no breaking changes ever. Adding a required field is breaking. Removing an enum value is breaking. Tightening a regex is breaking. Lowering a rate limit is breaking. Changing an error code's family is breaking.

Tokens carry an api_version_pinned. Customers stay on their pinned version until they explicitly bump. Older minors are retained for at least 24 months from deprecation, often longer.

The oasdiff CI gate blocks any PR that introduces a breaking change without bumping the minor.

10. Standards over proprietary

Where a standard exists, we use it. Where we have to invent, we publish the spec.

Our own conventions — typed IDs, scope-policy DSL, event sourcing model, ExecutionPlan grammar — are published in this docs site so customers can build against them confidently.

How this philosophy shows up in practice

• API Council review. Every new endpoint is reviewed against these ten principles before any code is written. The review minutes are recorded.
• API review checklist. The ~80-item checklist mechanically asks "does this endpoint follow principle N?" for each.
• Automated tests. The API consistency suite (P0.A9), spec linter (Spectral; P0.G8), and backwards-compat validator (oasdiff; P0.G9) catch the structural cases.
• Production-readiness review. Before any endpoint promotes Preview → Beta or Beta → GA, this philosophy is reviewed against actual behaviour.

See also

• Architecture overview — the system diagram and three architectural truths.
• Bounded contexts — how the code is organised.
• Capacity plan — how the system scales.
• API Council — the human design forum.
• API review checklist — the ~80-item checklist.