Managing multiple FHIR resources using Bundle - AWS HealthLake
Multiple CRUD operationsGrouped resources

Managing multiple FHIR resources using Bundle

In the HL7 FHIR R4 specification, bundles are simply a collection of resources. HealthLake supports creating a Bundle resource type in a FHIR REST API request, and using a bundle transaction to perform multiple CRUD operations in a single FHIR REST API request. In a bundle transaction, you must specify the bundle type as batch in the FHIR REST API request.

All bundle requests are recorded by AWS CloudTrail. To learn more about using CloudTrail with HealthLake, see Logging AWS HealthLake API Calls with AWS CloudTrail.

HL7 FHIR R4 Resources (External)

The sections below describe how to structure a FHIR REST API request in order to either create a new Bundle resource or to process resources individually using bundle transactions.

Differences between the HealthLake console, the AWS CLI, and the AWS SDKs

The HealthLake console only supports Bundle type operations where the Bundle resource type is specified in the FHIR REST API request URL.

Performing multiple CRUD operations using FHIR bundles

When no resource type is specified in your request URL, the FHIR REST API request is parsed as individual data store transactions. Each CRUD operation provided in the JSON body is evaluated and a specific HTTP status code returned. HealthLake supports the Bundle type batch.

To perform multiple CRUD operations in a single FHIR REST API request do the following:

The following list shows truncated portions of a request body used in bundle FHIR REST API request. For a full request body, see Creating a bundle request involving multiple CRUD operations.

  1. Do not specify a resource type in your POST request:

    POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/

  2. In the request body specify the Bundle type as "type": "batch"

  3. In the request body specify resource-specific data for each CRUD interaction starting with the resource key.

  4. Each CRUD operation is specified as a request in the request body as follows: 

    { ...
  "request" : {
    "method" : "HTTP-VERB",
    "url" : "FHIR-RESOURCE-TYPE-URL"
  }
  ...
}

In the JSON response, you get an HTTP status code for each CRUD operation specified in the request.

HealthLake limits Bundle transactions

The following is an example of a Bundle operation containing multiple CRUD operations.

Example – Creating a Bundle request involving multiple CRUD operations.

To make a FHIR REST API request that performs multiple CRUD operations, you must make a POST request using your data store endpoint, and provide a JSON request body.

You can find your data store's endpoint in the HealthLake console under Data Stores or by using the DescribeFHIRDatastore operation in the AWS HealthLake API Reference.

POST Request

Make a POST request using your data store's endpoint. Use the next tab, JSON Request Body to see the required elements of the request body.

POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/
JSON Request Body

In the request body, you must provide the following key:value pairs along with any other FHIR resource-specific data about the individual CRUD requests. The first example shows a truncated JSON request body highlighting the required elements. The second example is shows a full JSON request body.

{
  "resourceType": "Bundle",
  "id": "bundle-batch-operation",
  "meta": {
    "lastUpdated": "2014-08-18T01:43:30Z"
  },
  "type": "batch", ## Required
  "entry": [
    {
      ## CRUD Transaction - 1
      "resource": {
        "resourceType": "Patient",
        ...
      },
      "request": { ## Required
        "method": "POST",
        "url": "Patient"
      }
    },
    {
      ## CRUD Transaction - 2
      "resource": {
        "resourceType": "Medication",
        ...
      },
      "request": { ## Required
        "method": "POST",
        "url": "Medication"
      }
    }
  ]
}

Here's a full example that shows creating a new Patient and Medication resource type.

{
  "resourceType": "Bundle",
  "id": "bundle-transaction",
  "meta": {
    "lastUpdated": "2014-08-18T01:43:30Z"
  },
  "type": "batch",
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "meta": {
          "lastUpdated": "2022-06-03T17:53:36.724Z"
        },
        "text": {
          "status": "generated",
          "div": "Some narrative"
        },
        "active": true,
        "name": [
          {
            "use": "official",
            "family": "Jackson",
            "given": [
              "Mateo",
              "James"
            ]
          }
        ],
        "gender": "male",
        "birthDate": "1974-12-25"
      },
      "request": {
        "method": "POST",
        "url": "Patient"
      }
    },
    {
      "resource": {
        "resourceType": "Medication",
        "id": "med0310",
        "contained": [
          {
            "resourceType": "Substance",
            "id": "sub03",
            "code": {
              "coding": [
                {
                  "system": "http://snomed.info/sct",
                  "code": "55452001",
                  "display": "Oxycodone (substance)"
                }
              ]
            }
          }
        ],
        "code": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "430127000",
              "display": "Oral Form Oxycodone (product)"
            }
          ]
        },
        "form": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "385055001",
              "display": "Tablet dose form (qualifier value)"
            }
          ]
        },
        "ingredient": [
          {
            "itemReference": {
              "reference": "#sub03"
            },
            "strength": {
              "numerator": {
                "value": 5,
                "system": "http://unitsofmeasure.org",
                "code": "mg"
              },
              "denominator": {
                "value": 1,
                "system": "http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm",
                "code": "TAB"
              }
            }
          }
        ]
      },
      "request": {
        "method": "POST",
        "url": "Medication"
      }
    }
  ]
}
JSON Response

To confirm the creation of the resources specified in the example bundle transaction, you get 201 Created HTTP status code for each included CRUD operation. When a CRUD operation fails you get 400 series HTTP status indicating why the individual request failed.

{
  "resourceType": "Bundle",
  "type": "batch-response",
  "timestamp": "2022-06-15T01:31:34.300+00:00",
  "entry": [
    {
      "response": {
        "status": "201",
        "location": "Patient/fd68ce38-ba30-4459-9eeb-476ad9f4f4ca",
        "lastModified": "2022-06-15T01:31:34.180+00:00"
      }
    },
    {
      "response": {
        "status": "201",
        "location": "Medication/5bf3b8cc-4076-4219-aba1-e2c53d7916f4",
        "lastModified": "2022-06-15T01:31:34.180+00:00"
      }
    }
  ]
}

Grouping resources as a Bundle resource type

To create a new Bundle resource type, you must specify Bundle in the FHIR REST API request and provide a valid JSON body containing the resources you want grouped together.

When Bundle is specified in the request URL, the contents of the JSON request body are saved in your HealthLake data store as-is. Therefore, no CRUD operations can be performed on the individual resource types. Bundles of this type are assigned a single new resource ID. Because the resources are saved as-is, you cannot make GET or POST requests on individual resources saved in the Bundle resource type.

Note

The HL7 FHIR R4 specification also supports grouping resources using Group, Composition, and List. When you create these resource types, the individual resources are not contained directly. Instead, they use the Reference element to point to the individual resources. Using these resources types therefore allow you to modify the individual resources contained within them.

To create a Bundle resource type, you must specify it in your POST request and provide a JSON enumerating the resources you want to be included.

Example – Creating a Bundle resource using a POST request

To create a bundle resource do the following

  1. Format a FHIR REST API request as follows:

    POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Bundle

  2. Provide JSON body which specifies the resources you want to group together. This example groups two patient resources.

    {
  "resourceType": "Bundle",
  "id": "bundle-transaction",
  "meta": {
    "lastUpdated": "2018-03-11T11:22:16Z"
  },
  "type": "document",
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        "name": [
          {
            "family": "Smith",
            "given": [
              "Jane"
            ]
          }
        ],
        "gender": "female",
        "address": [
          {
            "line": [
              "123 Main St."
            ],
            "city": "Anycity",
            "state": "Any State",
            "postalCode": "12345"
          }
        ]
      }
    },
    {
      "resource": {
        "resourceType": "Patient",
        "name": [
          {
            "family": "Jackson",
            "given": [
              "Mateo"
            ]
          }
        ],
        "gender": "male",
        "address": [
          {
            "line": [
              "1234 Main St."
            ],
            "city": "Anycity",
            "state": "Any State",
            "postalCode": "12345"
          }
        ]
      }
    }
  ]
}