Platform interoperability — API documentation (REST + FHIR R4)

Document version: 1.1
Date: 2026-03-22
Status: Supplementary to Kong infra/kong/*.yml and module API_DOCS.md

1. API Conventions

1.1 Base URLs

All routes are served through the Kong API Gateway.

Internal REST (product APIs):

Local dev: http://localhost:8000/v1/{service-specific-path}

FHIR R4 (interoperability APIs):

Local dev: http://localhost:8000/fhir/R4/{ResourceType}

1.2 Authentication

All endpoints require a Bearer JWT issued by Keycloak.

Clinician/staff apps use staff realm/client (deployment-specific).
Patient portal uses a portal realm/client with more restrictive scopes.

1.3 Common headers

Header	REST	FHIR	Description
`Authorization`	✅	✅	`Bearer {JWT}`
`X-Request-ID`	◇	◇	Correlation UUID; echoed in responses/logs
`Accept-Language`	◇	◇	`en`, `ar`, `ps`, `fa-AF`
`Content-Type`	✅ (write)	✅ (write)	`application/json` (REST), `application/fhir+json` (FHIR)

1.4 Error formats

REST errors use the platform JSON envelope:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "details": { "field": ["Must be a valid UUID"] }
  },
  "correlationId": "uuid",
  "timestamp": "2026-02-28T10:00:00Z"
}

FHIR errors return OperationOutcome:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "MODULE_NOT_ACTIVE"
    }
  ]
}

2. Kong routing table (reference)

Route Prefix	Upstream Service	Notes
`/v1/registration/*`	`registration`	Core REST
`/v1/scheduling/*`	`scheduling`	Core REST
`/v1/provider-directory/*`	`provider-directory`	Core REST
`/v1/facility/*`	`facility`	Core REST
`/v1/patient-chart/*`	`patient-chart-service`	Core REST
`/v1/clinical-notes/*`	`clinical-notes`	Core REST
`/v1/orders/*`	`orders`	Core REST + interop
`/v1/results/*`	`results`	Core REST + interop
`/v1/medications/*`	`medication`	Core REST
`/v1/problem-list/*`	`problem-list`	Core REST
`/v1/allergies/*`	`allergies`	Core REST
`/v1/vitals/*`	`vitals`	Core REST
`/v1/immunizations/*`	`immunizations`	Licensed add-on
`/v1/care-plans/*`	`care-plans-service`	Licensed add-on
`/v1/digital-communication/*`	`digital-communication`	Licensed add-on (messaging + virtual visits + tenant VC config)
`/v1/portal/*`	`patient-portal-api`	Licensed add-on
`/v1/lis/*`	`laboratory-lis`	Licensed add-on
`/v1/radiology/*`	`radiology-pacs`	Licensed add-on
`/v1/billing/*`	`billing`	Licensed add-on
`/v1/insurance/*`	`insurance`	Licensed add-on
`/v1/claims/*`	`claims`	Licensed add-on
`/fhir/R4/*`	`fhir-gateway`	Consolidated FHIR surface
`/v1/interop/*`	`hl7v2-interop`	Admin endpoints; MLLP listener is direct

3. FHIR R4 API (via `fhir-gateway`)

3.1 Supported resources (baseline)

The gateway exposes a consolidated surface across platform services. Resource ownership rules are defined in SPEC.md §6.

Minimum resources:

Core admin/clinical: Patient, Encounter, Appointment, Practitioner, PractitionerRole, Organization, Location
Clinical facts: AllergyIntolerance, Condition, Observation, ServiceRequest, DiagnosticReport, Specimen, MedicationRequest
Add-ons: Immunization, CarePlan, Goal, Communication
Financial: Account, ChargeItem, Invoice, Coverage, Claim (baseline)

3.2 CapabilityStatement

GET /fhir/R4/metadata

3.3 Common search expectations

All searches return a Bundle of type searchset.
Pagination uses _count and link relations.

3.4 Examples

Search released results for patient (lab + imaging):

GET /fhir/R4/DiagnosticReport?patient=Patient/{id}&status=final

Search immunizations for patient:

GET /fhir/R4/Immunization?patient=Patient/{id}

4. Add-on services — internal REST APIs

These endpoints are product/UI APIs. They may be thin wrappers over FHIR interactions where feasible.

4.1 Immunizations (`immunizations`)

GET /v1/immunizations?patientId={uuid}&from={date}&to={date}
POST /v1/immunizations
PUT /v1/immunizations/{id}
POST /v1/immunizations/{id}/refuse
GET /v1/immunizations/{patientId}/forecast (optional)

4.2 Care Plans (`care-plans-service`)

POST /v1/care-plans/careplans
GET /v1/care-plans/careplans?patientId={uuid}&status=active|completed
GET /v1/care-plans/careplans/{id}
PUT /v1/care-plans/careplans/{id}
POST /v1/care-plans/careplans/{id}/review
POST /v1/care-plans/careplans/{id}/goals
POST /v1/care-plans/careplans/{id}/activities

4.3 Messaging (`digital-communication` — threads)

Canonical spec: specs/modules/digital-communication/API_DOCS.md. Historical paths: specs/modules/messaging/API_DOCS.md.

POST /v1/digital-communication/messaging/threads
GET /v1/digital-communication/messaging/threads (list / inbox; optional patientId, orderId)
GET /v1/digital-communication/messaging/threads/{threadId}
PATCH /v1/digital-communication/messaging/threads/{threadId}/archive
POST /v1/digital-communication/messaging/threads/{threadId}/escalate
POST /v1/digital-communication/messaging/threads/{threadId}/messages
GET /v1/digital-communication/messaging/threads/{threadId}/messages
POST /v1/digital-communication/messaging/threads/{threadId}/read (body: messageIds[])

4.4 Patient Portal (`patient-portal-api`)

GET /v1/portal/me
GET /v1/portal/record/summary
GET /v1/portal/appointments
POST /v1/portal/appointments/requests
GET /v1/portal/results (released-only)
POST /v1/portal/demographics/updates
GET /v1/portal/messages (if messaging enabled)

4.5 Laboratory / LIS (`laboratory-lis`)

GET /v1/lis/catalog
POST /v1/lis/accessions
POST /v1/lis/specimens/{id}/collect
POST /v1/lis/specimens/{id}/receive
POST /v1/lis/results (manual entry)
POST /v1/lis/results/{id}/verify
POST /v1/lis/results/{id}/release

4.6 Radiology / PACS (`radiology-pacs`)

Routes match Nest controllers (no /v1/radiology prefix); Kong exposes:

GET /studies?patientId={uuid} / POST /studies / GET /studies/{id} / POST /studies/{id}/available
POST|GET /reports … (see module API_DOCS.md)
POST /studies/{id}/viewer-launch (signed viewer handoff)
POST|GET /pacs-endpoints (admin)
FHIR: GET /fhir/R4/ImagingStudy via fhir-gateway /fhir → owning service

4.7 Billing / Insurance / Claims

Billing

POST /v1/billing/charges
GET /v1/billing/accounts?patientId={uuid}
POST /v1/billing/invoices
POST /v1/billing/payments

Insurance

GET /v1/insurance/coverage?patientId={uuid}
POST /v1/insurance/coverage
POST /v1/insurance/eligibility/check
POST /v1/insurance/authorizations

Claims

POST /v1/claims/from-encounter/{encounterId}
POST /v1/claims/{id}/validate
POST /v1/claims/{id}/submit
GET /v1/claims?status=draft|submitted|paid
POST /v1/claims/remittances/import

5. HL7 v2 Interop Admin APIs (`hl7v2-interop`)

POST /v1/interop/connectors (create connector)
GET /v1/interop/messages?connectorId=&status=
GET /v1/interop/messages/{id}
POST /v1/interop/messages/{id}/reprocess

MLLP listeners are configured per connector and run as TCP endpoints (not via Kong).

1. API Conventions​

1.1 Base URLs​

1.2 Authentication​

1.3 Common headers​

1.4 Error formats​

2. Kong routing table (reference)​

3. FHIR R4 API (via fhir-gateway)​

3.1 Supported resources (baseline)​

3.2 CapabilityStatement​

3.3 Common search expectations​

3.4 Examples​

4. Add-on services — internal REST APIs​

4.1 Immunizations (immunizations)​

4.2 Care Plans (care-plans-service)​

4.3 Messaging (digital-communication — threads)​

4.4 Patient Portal (patient-portal-api)​

4.5 Laboratory / LIS (laboratory-lis)​

4.6 Radiology / PACS (radiology-pacs)​

4.7 Billing / Insurance / Claims​

5. HL7 v2 Interop Admin APIs (hl7v2-interop)​