ADR-0002: Use REST with OpenAPI and shared schemas
- Status: Accepted
- Date: 2026-09-19
- Scope: API boundary
Context
Mobile and future internal clients need a clear, inspectable interface. Input must be validated at the trust boundary, errors must be predictable, and asynchronous analysis must not hold an interactive request open.
Decision
- Use resource-oriented HTTPS REST endpoints.
- Generate a non-production OpenAPI description from the API boundary.
- Reuse provider-independent shared schemas where doing so does not expose server internals.
- Validate all untrusted request and provider data.
- Return typed errors with stable machine codes and safe human messages.
- Represent long-running work with accepted/pending resources and status retrieval rather than a synchronous provider wait.
- Version breaking changes deliberately; additive compatibility is preferred.
OpenAPI is a contract and development aid, not evidence that a product workflow exists. At M0, only the scaffolded API surfaces such as health and non-production OpenAPI are claimed.
Consequences
- Clients and contract tests can reason about requests, responses, and errors.
- HTTP semantics, pagination, idempotency, and deprecation need consistent governance.
- Shared schema reuse reduces drift but must not leak persistence or vendor objects.
- Asynchronous resources add state and retry complexity.
Follow-up
- Define authentication and object-authorization requirements before product endpoints.
- Add compatibility tests and redact examples before any broader OpenAPI exposure.
- Specify idempotency, pagination, rate-limit, and correlation conventions before beta.