ADR 0025: External and internal API documentation

Ratification

This ADR decides how we split documentation for external integrators (partners, client developers) and engineers in this repo. Git history on main is the record for this file.

• Discussion Issue: optional — link when opened with [ADR] title
• Merge PR: see git history for this file
• Accepted: 2026-04-14

Context

Why this matters: One group needs a stable contract and release notes; the other needs business rules, how things behave in production, and why we built it that way — hard to put fully in OpenAPI. If we mix both in random prose, external readers see internal detail they do not need, and engineers search code when text is missing.

We already govern HTTP quality via ADR 0007 (OpenAPI snapshot, examples, CI) and public change history via ADR 0013. This ADR does not change those rules. It only names which artifact is official for which audience and where internal narrative lives (docs/internal/; see ADR 0026).

Decision

1. External contract (integrators). The OpenAPI document committed under docs/openapi/ (baseline snapshot and the same contract exposed at runtime when the app serves /openapi.json) is the sole normative description of the public HTTP API for external development: paths, methods, schemas, declared errors, examples, and documented headers. Partners and third-party clients should treat it as immutable truth for what we publish at a given release; changes flow through versioning and changelog policy (ADR 0004, ADR 0013).
2. External discovery aids. Swagger UI at /docs (when the app runs) and the static docs/openapi/openapi-explorer.html page are views on that contract; they are not independent sources of truth. If explorer text disagrees with the committed baseline after a merge, the fix is to align code and baseline (ADR 0007), not to treat the browser copy as authoritative.
3. Internal service documentation. Narrative that explains why the API behaves as it does, business invariants, cross-cutting processes (idempotency, error monitoring expectations, messaging topics), and traceability of decisions over time lives under docs/internal/ as HTML, governed by ADR 0026. Layout is multi-page: a landing page, service overview, an HTTP API hub under docs/internal/api/, and per-resource folders with a single hub (index.html) plus optional per-endpoint pages — see ADR 0026 and docs/howto/internal-service-docs-layout.html (contributor layout; STRUCTURE.md links there). It does not replace OpenAPI for external consumers.
4. Python API reference. Generated HTML under docs/api/ remains the reference for in-repo Python modules (per ADR 0016), distinct from HTTP OpenAPI and from docs/internal/.

Scope

• In scope: Audience split, location of internal HTML docs, primacy of OpenAPI for external HTTP contract.
• Out of scope: A separate public developer portal product, monetization, or org-wide API catalogue outside this repository.

Relationship to other artifacts

Alternatives considered

1. Single prose manual for everything.
   • Pros: one place to open.
   • Cons: duplicates OpenAPI; drifts from CI-checked contract; poor for machine clients.
2. OpenAPI-only, no internal tree.
   • Pros: minimal files.
   • Cons: business rules and rationale scatter across code review and chat; disputes default to reading code.

Consequences

Positive

• Clear expectation: integrators trust OpenAPI + changelog; engineers extend internal docs when behavior is non-obvious.
• Aligns with existing governance (ADR 0007, 0013) without changing contract-test meaning.

Trade-offs

• Two maintained surfaces (OpenAPI + internal HTML) require discipline; internal pages must link to operations and PRs when they change behavior.

Page history