JFT WriteAPI Overview
Note
Some of the features are not implemented yet. See Roadmap and the OpenApi docs for latest status.
The WriteAPI includes endpoints for submitting events and event status updates. As suggested by FHIR, the resource types used to represent events are a part of the endpoint addresses. The resource types currently supported are:
- Bundle: For single event which is represented by multiple resources.
- Composition: For clinical notes and documents.
- MedicationDispense: For successful medication dispensing events.
Example files are available here.
Submitting events
Submitting events is done by making POST requests to the resource type endpoints.
Format: POST /v1/<ResourceType>
For example: POST /v1/Composition submits an event represented by a FHIR Composition resource.
The endpoints respond with 202 Accepted if the submitted event was successfully validated and saved for further processing.
The URL used to check updates on the submitted event's status is included in the response headers.
Journaling acknowledgement
When an event has been successfully journaled in an EHR system, the client can acknowledge this to JFT using these endpoints.
Format: POST /v1/<ResourceType>/{ResourceId}/$journaling-acknowledged
For example: POST /v1/MedicationDispense/123/$journaling-acknowledged registers acknowledge status for an event submitted as a FHIR MedicationDispense resource with resource ID 123
(resource IDs are actually represented as GUIDs).
The endpoints respond with 202 Accepted, and include a header pointing to the status URL for the event.
Validation
To ensure data quality and prevent the mixing of test and production data, the following checks are performed on every submission of events:
Format check
The API performs deserialization of the received JSON to ensure the content adheres to the FHIR R4 standard.
Requests with invalid JSON structures or missing mandatory FHIR elements are rejected with 400 Bad Request.
Handling of national identification numbers (NINs)
- Production env.: Only real Norwegian NINs are allowed.
- Test env.: Only synthetic identity numbers are allowed.
We recommend using SyntPop to generate valid synthetic test data for use in our test environments. More information can be found at NHN Developer Portal - SyntPop.
Handling of organization numbers
- Production env.: Only real Norwegian organization numbers are allowed.
- Test env.: Only synthetic organization numbers are allowed.
Note
Currently there is an exception for organization numbers in the claim orgnr_supplier.
Until further notice, real organization numbers in this claim are also accepted in Test.
Required claim
The orgnr_parent claim is required in the access token for all endpoints.
Its value must be the organization number of the municipality's main entity.
Optional header
When submitting events vendors are encouraged to include the header nhn-source-system in the request headers.
If present, the header value is used to enrich the event resource. The aim is to make it easier for EHR systems
to recognized the originator for the event. See EventLifecycle for an example.