Exporting data from your data store by using the FHIR REST API
Important
HealthLake data stores created prior to June 1, 2023 only support FHIR REST API based export job requests for system-wide exports.
HealthLake data stores created prior to June 1, 2023 do not support getting the status of an export using a GET
request on a data store's endpoint.
To make an export request using the FHIR REST API, you must have a IAM user, group, or role with the required permissions, specify $export
as part of the POST
request, and include request parameters in the body of your request. According to the FHIR specification, the FHIR server must support GET
requests, and can support POST
requests. In order to support additional parameters, a body is needed to start the export, therefore HealthLake supports POST requests.
All export requests you make using the FHIR REST API are returned in ndjson
format and exported to an Amazon S3 bucket. Each S3 object will contain only a single FHIR resource type.
You can queue export requests as per the AWS account quotas. To learn more about the Service Quotas associated with HealthLake, see AWS HealthLake endpoints and quotas.
HealthLake supports the following three types of bulk export endpoint requests.
Type | Descriptions | Syntax |
---|---|---|
System export |
Export all data from the HealthLake FHIR server. |
|
All patients |
Export all data relating to all patients including resource types associated with the Patient resource type. |
|
Group of Patients |
Export all data relating to a group of patients specified with a Group ID. |
|
Before you begin
Meet the following requirements to make an export request by using the FHIR REST API for HealthLake.
-
You must have set up a user, group, or role that has the necessary permissions to make the export request. To learn more, see Authorizing an export request.
-
You must have created a service role that grants HealthLake access to the Amazon S3 bucket to which you want your data to be exported. The service role must also specify HealthLake as the service principal. To learn more, see Creating a service role.
Authorizing an export
request
To make a successful export request using the FHIR REST API, authorize your user, group, or role m by using either IAM or OAuth2.0. You also must have a service role.
Authorizing a request by using IAM
When you make an $export
request, the user, group, or role must have StartFHIRExportJobWithPost
, DescribeFHIRExportJobWithGet
, and CancelFHIRExportJobWithDelete
IAM actions included in the policy.
Authorizing a request using SMART on FHIR (OAuth 2.0)
When you make an $export
request on SMART on FHIR enabled HealthLake data store, you need to have the appropriate scopes assigned. To learn more about supported scopes, see HealthLake data store FHIR resource specific scopes.
Making an export
request
This section describes the required steps you must take when making an export request by using the FHIR REST API.
To avoid accidental charges on your AWS account, we recommend testing your requests by making a POST
request without supplying the export
syntax.
To make the request, you must do the following:
-
Specify
export
in thePOST
request URL for a supported endpoint. -
Specify the required header parameters.
-
Specify a request body that defines the required parameters.
Step 1: Specify export
in the POST
request URL for a supported endpoint
HealthLake supports three types of bulk export endpoint requests. To make a bulk export request, you must make a POST
-based request on one of the three supported endpoints. The following examples demonstrate how to specify export
in the request URL.
-
POST https://healthlake.
your-region
.amazonaws.com/datastore/your-datastore-id
/r4/$export -
POST https://healthlake.
your-region
.amazonaws.com/datastore/your-datastore-id
/r4/Patient/$export -
POST https://healthlake.
your-region
.amazonaws.com/datastore/your-datastore-id
/r4/Group/ID
/$export
In that POST
request string, you can use the following supported search parameters.
Supported search parameters
HealthLake supports the following search modifiers in bulk export requests.
These examples include special characters which must be encoded prior to submitting your request.
Name | Required? | Description | Example |
---|---|---|---|
_outputFormat |
No | The format for the requested Bulk Data files to be generated. Accepted values are application/fhir+ndjson , application/ndjson , ndjson . |
|
_type |
No | A string of comma delimited FHIR resource types that you want included in your export job. We recommend including _type because this can have a cost implication when all resources are exported. |
&_type=MedicationStatement, Observation |
_since |
No | Resource types modified on or after the date time stamp. If a resource type does not have a last updated time they will be included in your response. | &_since=2024-05-09T00%3A00%3A00Z |
Step 2: Specify the required header parameters
To make an export request using the FHIR REST API, you must specify the following two header parameters.
-
Content-Type:
application/fhir+json
-
Prefer:
respond-async
Next, you must specify the required elements in the request body.
Step 3: Specify a request body the defines the required parameters.
The export request also requires a body in JSON
format. The body can include the following parameters.
To learn more, see Creating a service role
Key | Required? | Description | Value |
---|---|---|---|
DataAccessRoleArn | Yes | An ARN of a HealthLake service role. The service role used must specify HealthLake as the service principal. | arn:aws:iam:: |
JobName | No | The name of the export request. |
|
S3Uri | Yes | Part of an OutputDataConfig key. The S3 URI of the destination bucket where your exported data will be downloaded. | s3://DOC-EXAMPLE-DESTINATION-BUCKET/ |
KmsKeyId | Yes | Part of an OutputDataConfig key. The ARN of the AWS KMS key used to secure the Amazon S3 bucket. | arn:aws:kms: |
Example – Body of an export request made by using the FHIR REST API
To make an export request by using the FHIR REST API, you must specify a body, as shown in the following.
{
"DataAccessRoleArn": "arn:aws:iam::444455556666
:role/your-healthlake-service-role
",
"JobName": "your-export-job
",
"OutputDataConfig": {
"S3Configuration": {
"S3Uri": "s3://DOC-EXAMPLE-DESTINATION-BUCKET/EXPORT-JOB
",
"KmsKeyId": "arn:aws:kms:region-of-bucket
:444455556666
:key/1234abcd-12ab-34cd-56ef-1234567890ab
"
}
}
}
When your request is successful, you will receive the following response.
Response Header
content-location: https://healthlake.
your-region
.amazonaws.com/datastore/your-datastore-id
/r4/export/your-export-request-job-id
Response Body
{ "datastoreId": "your-data-store-id", "jobStatus": "SUBMITTED", "jobId": "your-export-request-job-id" }
Managing your export request
After making a successful export request, you can manage that request by using export
to describe the status of a current export request, and export
to cancel a current export request.
When you cancel an export request by using the REST API, you will only be billed for the portion of the data that was exported up to the time you submitted the cancel request.
The following topics describe how you can get the status on or cancel a current export request.
Canceling an export request
To cancel an export request, make a DELETE
request and supply the job ID in the request URL.
DELETE https://healthlake.
your-region
.amazonaws.com/datastore/your-datastore-id
/r4/export/your-export-request-job-id
When your request is successful, you receive the following.
{ "exportJobProperties": { "jobId": "your-original-export-request-job-id", "jobStatus": "CANCEL_SUBMITTED", "datastoreId": "your-data-store-id" } }
When your request is not successful, you receive the following.
{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "not-supported", "diagnostics": "Interaction not supported." } ] }
Describing an export request
To get the status of an export request, make a GET
request by using export
and your
.export-request-job-id
GET https://healthlake.
your-region
.amazonaws.com/datastore/your-datastore-id
/r4/export/your-export-request-id
The JSON response will contain an ExportJobProperties
object. It may contain the following key:value pairs.
Name | Required? | Description | Value |
---|---|---|---|
DataAccessRoleArn | No | An ARN of a HealthLake service role. The service role used must specify HealthLake as the service principal. | arn:aws:iam:: |
SubmitTime | No | The date time an export job was submitted. | Apr 21, 2023 5:58:02 |
EndTime | No | The time an export job was completed. | Apr 21, 2023 6:00:08 PM |
JobName | No | The name of the export request. |
|
JobStatus | No | Valid values are:
| |
S3Uri | Yes | Part of an OutputDataConfig object. The Amazon S3 URI of the destination bucket where your exported data will be downloaded. | s3://DOC-EXAMPLE-DESTINATION-BUCKET/ |
KmsKeyId | Yes | Part of an OutputDataConfig object. The ARN of the AWS KMS key used to secure the Amazon S3 bucket. | arn:aws:kms: |
Example : Body of a describe export request made using the FHIR REST API
When successful, you will get the following JSON response.
{ "exportJobProperties": { "jobId": "
your-export-request-id
", "JobName": "your-export-job
", "jobStatus": "SUBMITTED", "submitTime": "Apr 21, 2023 5:58:02 PM", "endTime": "Apr 21, 2023 6:00:08 PM", "datastoreId": "your-data-store-id
", "outputDataConfig": { "s3Configuration": { "S3Uri": "s3://DOC-EXAMPLE-DESTINATION-BUCKET/EXPORT-JOB
", "KmsKeyId": "arn:aws:kms:region-of-bucket
:444455556666
:key/1234abcd-12ab-34cd-56ef-1234567890ab
"" } }, "DataAccessRoleArn": "arn:aws:iam::444455556666
:role/your-healthlake-service-role
", } }