API path conventions (HTTP edge)
Normative tie-in: ARCHITECTURE_BASELINE.md §6 (internal REST base
/v1/{service-path}).
Intentional split: platform vs clinical
| Prefix | Typical consumers | Examples | Notes |
|---|---|---|---|
/api/{domain} | Platform admin UIs, IAM/tenant tooling | /api/iam, /api/tenants, /api/licenses, /api/access, /api/audit, /api/platform, /api/config | Historical and product-oriented grouping; still versioned at gateway via Kong service names. Not a violation of §6.1 when documented here. |
/internal/{domain} | Service-to-service on private networks | /internal/tenants, /internal/config, /internal/access/evaluate | IP-restricted or mesh-only in kong.yml; never browser-facing. |
/v1/... | Clinical and interop REST aligned to module specs | /v1/patients, /v1/notes, /v1/digital-communication/messaging, /v1/portal | Primary pattern for EHR module HTTP APIs. |
/fhir/... | FHIR R4 via gateway | /fhir/R4/..., /fhir/R4/metadata | Canonical clinical interchange per FHIR-first baseline. |
Convergence policy
- New clinical HTTP surfaces SHOULD use
/v1/...(or/fhir/R4/...when exposing FHIR). - New platform configuration or admin surfaces MAY continue
/api/...unless a major version migration is planned. - Any change that removes or renames a public Kong path requires a compatibility note in the module SPEC and TRACEABILITY updates.