Commure Bulk FHIR API

Version
1.0
Release Date
2020-02-06
Status
Live

If you’ve read through the overview of FHIR and it’s RESTful APIs, you should now see how the FHIR spec makes it easy to edit and manipulate individual resources. However, when dealing with large quantities of data, making individual resource requests will not be very performant and your users could spend a long time waiting.

With Commure’s support for Bulk FHIR, you can now import and export large number of resources asynchronously. This allows for distribution of data from and into other sources in a new way.

What is it?

Typically, sending data from one data warehouse to another would require exporting and importing CSV files and sharing them often via CDs. With the Bulk FHIR API, or sometimes referred to as Flat FHIR, the resources to be transferred between systems are stored in an NDJSON file format and ready to be imported to a new system.

Bulk FHIR specifies two complementary operations: $import and $export. The Commure FHIR server supports both.

How do I use it?

$export

To save FHIR resources on your server to the NDJSON format, you must first specify which resources you wish to export.

System-level export starts with all resources in your database and can be filtered using a couple optional parameters:

  • _type: comma separated list of resource types to export,
  • _typeFilter: comma separate list of filters that apply the specific type listed in the filter. Each filter has the structure [resourceType]?[FhirPath] e.g. Patient?gender=female. _typeFiler is implemented to filter resources in-memory and each resource only has to match one _typeFilter if there is one for its type i.e. _typeFilters for the same type are OR'd.

For example, if you wanted to export all female patients with a name starting with "A", the request would be:

/api/v1/r4/$export?_type=Patient&_typeFilter=Patient?name=A

Since this request could take a while to complete, you should call it asynchronously by including the request header pair Prefer: respond-async.

The response of this request will include a Content-Location that contains a link you can poll for status of the request. When it’s finished, the content location will return a 200 response code and a list of the locations for the output files in the output field of the response.

You can read more about this flow in the API documentation.

$import

If you wanted to import existing NDJSON files, you would make an $import request.

This request takes in a few parameters to specify where the files are located that it should import to your FHIR server. You can read about the parameters in the API docs.

Lastly, since this operation could also take some time to complete, you should also include the Prefer: respond-async header like you would for the $export request.