Data Exchange
This page contains instructions for handling FHIR data for the DBIR clinical registry.
- Introduction
- [Handling the FHIR Server](# FHIRServer)
- [Uploading a Single FHIR Resource](## Uploading a Single Resource)
- Retrieving a Patient(## Retrieving a Patient)
- Updating a Patient(## Updating a Patient)
- References
- Bundles
- Deleting a Patient
- References via Group Resources
Introduction
Communication with a FHIR endpoint is done using HTTP requests via the REST interface. Detailed descriptions can be found in the FHIR documentation. This document provides a brief overview of actions relevant to submissions of DBIR data.
Base URL
Assume the user has access to a specific FHIR REST endpoint URL, referred to as BASEURL. This URL ends with /fhir and serves as the base for all requests.
Authorization
FHIR endpoint communication uses the OAuth 2.0 protocol. All examples here assume the user has valid credentials and can authenticate using this protocol.
Currently, we use the Google Cloud Platform (GCP) implementation of a FHIR endpoint.
More information on GCP can be found here
Uploading FHIR Resources Resources can be uploaded in two ways:
One resource at a time.
Multiple resources simultaneously using a Bundle.
This can either be:
- A transaction bundle (all changes are applied only if every request is successful).
- A batch bundle (changes are applied independently).
- Uploading a single FHIR Resource
FHIRServer
Uploading a Single Resource
To upload a Patient resource, use an HTTP POST request.
For example:
curl -X POST \ -H "Content-Type: application/fhir+json" \ -d '{ "resourceType": "Patient", "gender": "male"}' \ [BASEURL]/Patient
Retrieving a Patient
Use the Patient ID returned during upload to fetch the resource:
curl -X GET \ -H "Content-Type: application/fhir+json; charset=utf-8" \ "[BASEURL]/Patient/{patient-id}"
Updating a Patient
Update the entire resource with PUT or modify specific fields using a PATCH. For example, changing the gender:
curl -X PATCH \ -H "Content-Type: application/json-patch+json" \ --data '[{"op": "replace", "path": "/gender", "value": "female"}]' \ "[BASEURL]/Patient/{patient-id}"
References
When uploading a resource that references others, include the relevant ID:
"subject": { "reference": "Patient/{patient-id}" }
Bundles
Bundles allow uploading multiple resources simultaneously. Use a POST request with the bundle file:
curl -X POST \ -H "Content-Type: application/fhir+json; charset=utf-8" \ -d @./examples/all.json \ "[BASEURL]"
Deleting a Patient
To delete a Patient and all related resources:
- Use the $everything request to fetch all associated resources.
- Delete related resources and the Patient via a transaction bundle.
Handling Group Resources
For Group resources referencing the Patient, update the group first to remove the Patient as a member, then proceed with deletion.
Bundles
In the previous examples, we uploaded only a single resource. In many cases, it will be desirable to upload multiple resources at once. This can be done one by one or all at once using a FHIR Bundle. In the examples folder, there is a file named all.json. This file contains all existing example data and can be uploaded to the FHIR server in one go using a batch transaction.
References in Bundles
The aforementioned Bundle file contains all examples, which also include local references to each other. In this way, multiple objects that reference each other can be created simultaneously. See here for official documentation on references within a Bundle. To reference another resource within the same bundle, you must provide a fullUrl for the resource within the bundle:
"fullUrl": "http://mrdm.nl/fhir/Patient/patient-1", "resource": {...}
The reference to this resource will look as follows within the referring resource:
"subject": { "reference": "http://mrdm.nl/fhir/Patient/patient-1" }
Other Operations
Within the bundle, you can define operations that should take place on the server. These could be new resources to be stored, updates to existing resources, deletions, or even search queries for which the user expects a response. This is specified under the request section of the Bundle.
Uploading a Transaction Bundle
To execute a Bundle on the server, send it with a POST request to the BASEURL of your FHIR server (without additional path segments):
curl -vX POST \ -H "Content-Type: application/fhir+json; charset=utf-8" -d @./examples/all.json \ "[BASEURL]"
Deleting a Patient
It may occur that all data related to a patient needs to be deleted. Unfortunately, this cannot currently be done with a single operation. The Patient is referenced by all elements associated with them, such as Observations, Episodes of Care, etc. These elements reference the Patient and thus "block" the deletion to maintain internal references.
** Finding and Deleting All Related Resources** First, all resources referencing the Patient resource must be identified. This can be done with the $everything request:
curl -vX GET [BASEURL]/Patient/$everything
This returns a list of all existing resources related to the patient. All these objects can then be deleted simultaneously using a Bundle that lists all the resources to be deleted.
This bundle must be constructed manually based on the information from the $everything request. Here is an example where a Patient, an Encounter, and an Observation are deleted at the same time:
{ "resourceType": "Bundle", "type": "transaction", "entry": [ { "request": { "method": "DELETE", "url": "Patient/0f6e2ea3-cf16-4b16-a638-4fff27dad3ee" } }, { "request": { "method": "DELETE", "url": "Encounter/16ba7f9f-fe78-42eb-a413-c9f239674bab" } }, { "request": { "method": "DELETE", "url": "Observation/b2834cb4-6229-4590-b46c-cc1675dcfa68" } } ] }
References via Group Resources
If you provide information about groups, the process becomes slightly more complex.
According to the FHIR definition, groups make "forward references" to the patients included in the group. However, it is not desirable to delete the group itself. Group resources should therefore be excluded from the deletion request. In such cases, the Group resource must first be updated by removing the reference to the patient to be deleted as a member in the group, while keeping the other patient members intact.
Here is an example of the member section of a Group resource, where two patients are mentioned:
"member": [ { "entity": { "reference": "Patient/0f6e2ea3-cf16-4b16-a638-4fff27dad3ee" } }, { "entity": { "reference": "Patient/fe7f78c4-7d2e-4d93-9a82-52f924011b27" } } ]
In this case, the Group resource (specifically the member section) must first be updated to remove the patient to be deleted. After this update, a new $everything request for the Patient can be issued, and the group will no longer appear in the list. Then all remaining resources can safely be deleted.
Steps to Delete a Patient
- Retrieve all resources related to the patient using the $everything request.
- If any Group Resources are included:
- Update each Group resource from this request to remove the unwanted patient from the member section of the group.
- Issue a new $everything request for the patient (now excluding the groups where they were removed).
- Delete all remaining resources by including them in a transaction-Bundle with the DELETE method.