Publish Box goes here

Internal HTTP API

Internal HTTP API

The prototype exposes simple local HTTP endpoints for systems that want to integrate without implementing the FHIR Subscription protocol themselves.

These endpoints are intentionally not the national exchange contract. They are the local integration contract between an adapter and the system behind it.

Subscriber-Side API

Use this API when a receiving or processing system wants to subscribe to source events.

POST /subscriber/internal/subscriptions
Content-Type: application/json

{
  "topic": "https://fhir.cumuluz.org/subscription-topic/heart-failure-daily-check",
  "patientId": "hf-patient-001",
  "content": "empty"
}

The subscriber adapter role turns this into a FHIR R4 Subscription and sends it to the source adapter role.

Request fields:

• topic: canonical URL of the topic to subscribe to;
• patientId: patient scope for this subscription;
• content: Backport payload content mode. This prototype uses empty, because event data is pulled after notification.

Expected behavior:

• first request for endpoint, topic and patient creates a subscription;
• repeated request for the same endpoint, topic and patient returns the existing subscription;
• request for another patient creates another subscription.

Source-Side Event API

Use this API when a source system wants to tell its local adapter that new event data exists.

POST /source-system/internal/events/heart-failure-daily-check
Content-Type: application/json

{
  "patientId": "hf-patient-001",
  "weightKg": 83.4,
  "dyspnea": "toegenomen kortademigheid bij traplopen",
  "status": "attention-needed"
}

The mock source system stores simple FHIR R4 data and sends a source-event signal to the source adapter. The adapter handles subscription matching and notification delivery.

Request fields:

• patientId: patient the event belongs to;
• weightKg: example body weight value;
• dyspnea: symptom text;
• status: example daily-check status.

In a real source integration, this endpoint could be replaced by a message queue, database event, domain event API or FHIR write hook. The important point is that the source system signals an event without managing subscriptions itself.

Source-System FHIR API

The minimum mock source-system FHIR API is:

GET /source-system/fhir/metadata
GET /source-system/fhir/Patient?patient={id}
GET /source-system/fhir/Observation?patient={id}
GET /source-system/fhir/Observation?notification-id={notification-id}
GET /source-system/fhir/QuestionnaireResponse?patient={id}
GET /source-system/fhir/QuestionnaireResponse?notification-id={notification-id}

The adapter uses the notification-id searches to assemble the notified-pull response. No Subscription endpoint is required on the source system.

Source Adapter FHIR API

External subscribers interact with the source adapter through FHIR:

GET /source-adapter/fhir/metadata
GET /source-adapter/fhir/Basic
POST /source-adapter/fhir/Subscription
GET /source-adapter/fhir/Subscription/{id}
DELETE /source-adapter/fhir/Subscription/{id}
GET /source-adapter/fhir/$notify-pull?notification-id={notification-id}

GET /source-adapter/fhir/Basic returns the prototype topic catalog as R4 Basic resources.

POST /source-adapter/fhir/Subscription accepts an R4 Subscription with R5 Backport topic and payload-content extensions.

GET /source-adapter/fhir/$notify-pull returns the event-specific FHIR searchset Bundle.

Demo state

GET /api/state

This returns the UI state: topics, active subscriptions, source events, received notifications and transport log entries.