Using open source FHIR APIs with FHIR Works on AWS

September 8, 2021: Amazon Elasticsearch Service has been renamed to Amazon OpenSearch Service. Visit the website to learn more.

In September 2019, we published a blog post, Building a Serverless FHIR Interface on AWS, which explained why customers might want to use FHIR (Fast Healthcare interoperability Resources) as a healthcare interface, and why serverless technology is a cost-efficient and flexible approach to these interfaces. The post explained the basic concepts underpinning FHIR, and how to go about creating a few of the basic FHIR Resource types (Patients, Observations, and Bundles). FHIR is gaining popularity around the world —especially in the US— where it is required by the 2021 CMS mandate. This is a problem for partners and customers who provide services for others, but who are struggling to build their own cost-effective FHIR stack.

In this post we explain how a new open source project in AWS, FHIR Works on AWS, is available to these customers to accelerate their use of FHIR in their own products. We provide an overview of the software package and explain how to get started with it.

Introduction

With healthcare data increasingly and almost entirely digitized, healthcare organizations have an opportunity to use this data to improve patient outcomes and operational efficiency. However, healthcare is littered with disparate medical systems with interfaces that are either proprietary or that conform to older standards, such as HL7 v2, IHE, CDA, among others. Implementations of earlier interface standards are frequently inconsistent, and hence fail to achieve usable healthcare interoperability. This leads to a situation in which data are digitally available but not generally accessible.

Recently efforts have been made to address this by issuing regulations requiring the accessibility of data and the standards used to achieve this. In the US, for example, a 2020 mandate from the Center of Medicare and Medicaid Services (CMS) aims to enforce by 2021 standardized healthcare data interoperability, first by providing patient access to data free of charge, and subsequently by mandating interfaces and data elements to be shared between healthcare systems.

Overview of the solution

Building on the aforementioned blog post, AWS has created an open source project, FHIR Works on AWS, an open source software toolkit that can be used to add capabilities of a FHIR interface to existing healthcare software. It implements a serverless FHIR API that supports the majority of FHIR Resource types and the most important operations. It also provides a set of architecture patterns to guide customers and partners through the process of designing and building integrations to their existing systems.

FHIR Works aims to help software engineers at independent software vendors, system integrators or healthcare customers to enhance their own products to provide access to data in those systems to mobile devices and web portals through integrating the FHIR standard APIs. It also allows these customers and partners to build connectors between their legacy and proprietary interfaces to the current FHIR standard. Finally, it includes guidance on how to customize the default FHIR Works on AWS API to their individual needs with specific FHIR Implementation Guides.

Many integration use cases require the ability to connect to a FHIR interface on one side and to legacy environments on the other. To help customers and partners achieve external legacy connectivity, FHIR Works on AWS includes an Integration Framework. This enables users to create their own Transforms that connect FHIR Works on AWS to any external interface, or to consume others published as open source or to the AWS Marketplace, opening up additional revenue opportunities for the partners creating them.

Different data access scenarios sometimes require a data store optimized for those use cases, and so the software also includes a storage abstraction layer that enables customer developers to substitute the default storage of the underlying architecture—Amazon Simple Storage Service (Amazon S3) and Amazon DynamoDB—with alternative storage services, such as Amazon Relational Database Service (Amazon RDS), Amazon Redshift, Amazon Neptune, Amazon Quantum Ledger Database (Amazon QLDB), etc.

FHIR Works on AWS is installed using the Serverless Framework, making it straightforward to customize using the widely known TypeScript programming language. The framework sets up the API endpoints and logic in the customer’s account, implemented using Amazon API Gateway, AWS Lambda, Amazon DynamoDB, Amazon Cognito, Amazon S3, and AWS Key Management Service (AWS KMS), along with Amazon Elasticsearch Service (Amazon ES).

This diagram explains the interaction between the individual components:

Walkthrough

With this software package, AWS aims to serve customers and partners who have engineering resources available and need to augment their own software solutions with FHIR API endpoints, or who need to build new software solutions that interface between FHIR APIs and existing systems with other interfaces, such as HL7 v2, HL7 v3, IHE, etc. The software package is especially interesting for those customers and partners whose products don’t have their own FHIR APIs, and who are not set up to build their own implementation, or who wish to use an open source stack to accelerate their software solutions.

Authentication

To connect to the FHIR Works on AWS APIs successfully, the user first must obtain an Amazon Cognito access token. Out of the box, Amazon Cognito is used for authentication, which, due to Amazon Cognito’s ability to federate with other identity providers, also allows for authentication against other systems, such as AWS Directory Service for Microsoft Active Directory. Systems or users accessing the APIs also must have an API key, which will have been generated during installation. This way a two-tier authentication is facilitated for additional security.

Authentication addresses both the client system and the user of that system:

1. An API Gateway Key is provided to each external client system to authenticate it to the API. During installation only one key is generated. Admins will need to add keys for additional client systems based on their knowledge of the deployment context.
2. An Amazon Cognito access token is used to authenticate the user making the request—either using the external system or directly against the APIs.

Each user will have their own Amazon Cognito Identity. This enables system administrators and auditors audit access on all resources—by both system and by who made the request— giving them visibility of where all requests were made from and who made them.

With this key and access token, a secure HTTPS connection is made to the REST endpoint of the FHIR API. This request is forwarded by API Gateway to the AWS Lambda function implementing the FHIR logic to process the request.

Depending on the FHIR Operation in the request, the AWS Lambda function either accesses the FHIR persistence store (Amazon DynamoDB by default), the search subsystem (Amazon ES), or Amazon S3 to generate signed URLs for larger objects. Writes to Amazon DynamoDB are replicated asynchronously to Amazon ES to enable a more flexible search experience.

Amazon DynamoDB can be substituted with other data stores by the customer to satisfy different use cases when incorporating FHIR Works on AWS into their solution.

Authorization

In this first release of FHIR Works on AWS, authorization is done using a Role-Based Access Control (RBAC). This restricts access to FHIR Operations and Resources based on a few simple role definitions that can be associated with users: auditor, practitioner, and non-practitioner. FHIR Works on AWS will be providing more sophisticated authorization in future releases, including SMART on FHIR.

Audit logging

To enable administrators and auditors to trace what patient information has been accessed by which user and when it was accessed, the API tracks all data access requests and responses. Requests and responses are intercepted by API Gateway and logged to Amazon CloudWatch. Customers and partners can then run analytics on these logs as with other AWS products.

Although CloudWatch is a convenient way to store such data, it comes at a higher price than S3. Thus, FHIR Works on AWS includes optional scripts to archive the audit logs to an encrypted S3 bucket for cost reduction. Customers can achieve further cost savings by extending these scripts to move the audit data into Amazon Simple Storage Service Glacier.

Binary resources

Binary resources are challenging in the world of REST APIs, because transfers can exceed endpoint timeouts due to their size. Binary resources can be anything from small MRI images to large images or a series of images, as well as genomic data or EKG wavelengths. The slower transfers associated with these larger objects can quickly exceed limits on timeouts and payload sizes (6 and 10MB respectively for API Gateway and Lambda). Additionally, BASE64-encoded transmission of large files is inefficient through a REST API. This is an acknowledged issue with the FHIR specification that, at the time of this writing, is still awaiting an authoritative solution with current tendencies toward the path implemented by FHIR Works on AWS.

FHIR Works on AWS uses a creative approach to address this, combining Amazon S3 with RESTful APIs. If a client wants to write a binary resource, upon making the POST request, it receives a response containing a time-limited, pre-signed S3 URL. The client can then use this temporary URL to upload the object.

When retrieving the file, the response to the client’s GET request again includes a temporary S3 pre-signed URL that is used for the download.

To ensure this approach is secure, the pre-signed URLs’ lifetime is extremely short, so a response’s chance of being intercepted is extremely low; it would require the transmission’s HTTPS TLS key to be hacked and the response object to be interpreted within a few seconds. This approach makes it practically impossible to gain unauthorized access to binary resources by this means, and to receive security approval by AWS Application Security. A further applicable preventative control would be to limit access by source IP address to the S3 bucket in question, which would enable only permitted clients to issue requests using that pre-signed URL.

Access to the source code

Why not try out FHIR Works on AWS right away? To simplify the inclusion of FHIR Works on AWS into your own code, it is structured as separate packages with their own repositories based on functional boundaries. This way it is easy to replace, for example, the storage layer with a custom storage without jeopardizing compatibility or upgrade safety for the other functional components. The central installation source code repository is publicly available on GitHub. Here you can find references to the other packages and instructions on how to use and consume them.

Clone the repositories to access the entirety of its source code and scripts.

Installation

Installing the software is straightforward. Although the software’s main purpose is to provide customers and partners with source code to accelerate adding a FHIR API to their own solutions, testing the functionality first may be helpful.

For this purpose, the software provides simple install scripts for Linux (Amazon, Ubuntu), macOS, Windows, and a Docker container for operating systems beyond this list. Using one of these methods will create the API Gateway FHIR API, associated Lambda functions, and also provision Amazon Cognito, DynamoDB, Amazon ES, and S3. This provides a deployment that can function as a standalone server for users to immediately test its endpoints prior to dissecting the packages for incorporation into their own software projects.

The GitHub repositories contain a README.md file in Markdown format. (Use a Markdown viewer of your choice, such as MacDown for macOS or VS Code on Windows to view it appropriately formatted.) These files will be regularly updated with changes to the repository, and to educate users on the prerequisites and the installation process.

API endpoints

To connect to the API endpoints, an access token must be retrieved from Amazon Cognito, which also requires an API key to facilitate multi-factor security. This can be achieved using the Cognito APIs, or through a script provided with the software repository.

FHIR Works on AWS’ FHIR capabilities are being enhanced with additional functionality, which is regularly released to the open source repository. Based on instructions from the README file, after you receive an access token, a call to the deployment’s /metadata/ endpoint will reveal its FHIR Capability Statement.

For example, on a macOS in the repository’s ./scripts/ directory, execute the following command, substituting all variables based on the output of the following command:

AWS_ACCESS_KEY_ID=<ACCESS_KEY> AWS_SECRET_ACCESS_KEY=<SECRET-KEY> python3 init-auth.py <USER_POOL_APP_CLIENT_ID> <REGION>

This will return an authentication token that can used with the curl utility to access the /metadata endpoint. For example:

curl -H "Accept: application/fhir+json" -H "Authorization: Bearer ${TOKEN}" -H "x-api-key: ${<API-KEY>}" https://<hostname>/<stage>/metadata

All STU3 and R4.0.1 FHIR resources are implemented, although some—such as Audit and Subscription—are restricted to stubs at this time. Bundles are implemented, however, to ensure complex linked Resources can be added and retrieved, it is limited to 25 entries per bundle.

Postman samples

The package also contains sample files that enable customers to test connections to their deployment using the Postman tool. Inside the postman/ folder, a collection of sample requests on a limited number of resources enables that tool to connect to the deployment’s FHIR API endpoints and create Patient Resources, search them, retrieve them, and delete them (implemented as a soft-delete); and to store, retrieve, and delete Binary resources, as well as retrieve its Capability Statement.

Along with simple instructions on how to use these samples, this enables a user to test the endpoints, gain familiarity with FHIR, or test their own solutions once incorporated with FHIR Works on AWS.

Import the environments file and the sample scripts into Postman, modify the authentication information in the environments within Postman (based on the output of the init-auth.py script above), and start testing to your heart’s content.

Cleaning up

The FHIR Works on AWS software package installs AWS resources using the Serverless Framework. To maintain a clean environment, Serverless is also used to remove FHIR Works and any trace of it from your environment. See the README.md file for details.

Conclusion

With the ever-growing need for native FHIR API support in healthcare software, smaller customers and partners struggle to keep up with the demand. FHIR Works on AWS gives these customers an option to use open source code in their applications rather than having to invest in creating and maintaining their own implementation. FHIR Works on AWS is simple to install and the code is easy to modify and incorporate into any software solution.