AWS HealthLake FHIR API Documentation #

This document consolidates the technical specifications, implementation requirements, and Terms of Use for the AWS HealthLake FHIR API (R4), intended to satisfy the ONC 170.315 (g)(9) requirements for standardized API access to Electronic Health Information (EHI).

Section 1: API Syntax, Functions, and Error Handling #

API Name: AWS Healthlake FHIR API (R4)

Intended Audience: Developers building healthcare applications, clinical data repositories, and interoperability solutions for federal health agencies. This includes system integrators, EHR (Electronic Health Record) vendors, and public health data analysts who need to store, query, and manage Protected Health Information (PHI) in a standards-compliant manner.

1.1 API Syntax #

Feature	Specification
Architecture	RESTful API based on the HL7 FHIR Standard R4 release.
Protocol	HTTPS exclusively.
Data Format	JSON. All requests and responses use the FHIR JSON media type (application/fhir+json).
Base URL	https://healthlake.us-east-1.amazonaws.com/.healthlake.amazonaws.com/datastore/8d8ae0ebc52744d8d9c6af8009bef7e6/r4/

1.2 Function Names (FHIR Interactions & Endpoints) #

The API is resource-centric. Functions are performed via HTTP methods on FHIR resource endpoints.

Function	HTTP Method	Endpoint	Description
Create	POST	/{ResourceType}	Create a new resource instance. The server assigns the ID.
Read	GET	/{ResourceType}/{id}	Retrieve a specific resource by its logical ID.
Update	PUT	/{ResourceType}/{id}	Update an existing resource at a known URL.
Delete	DELETE	/{ResourceType}/{id}	Delete specific resources.
Search	GET	/{ResourceType}?{Parameters}	Search for resources based on criteria.

1.3 Required and Optional Parameters and their Data Types #

A. Create a Patient #

Component	Detail	Data Type/Value	Required?
Endpoint	POST /Patient	N/A
Header	Content-Type	application/fhir+json	Required
Header	Authorization	AWS4-HMAC-SHA256 … (SigV4)	Required
Request Body	FHIR Patient resource in JSON format.	JSON Object	Required
Body Field	resourceType	String: “Patient”	Required
Body Field	name.family	String: Family name.	Required
Body Field	name.given	Array of Strings: Given names.	Required
Body Field	gender	String: “male”, “female”, “other”, “unknown”	Optional
Body Field	birthDate	String: ISO 8601 Date, e.g., “1974-12-25”	Optional

B. Search for Observations #

Component	Detail	Data Type/Value	Required?
Endpoint	GET /Observation	N/A
Query Param	patient	String: Logical ID of a patient resource. e.g., patient=12345	Required
Query Param	category	Token: Classification of the observation. e.g., category=vital-signs	Optional
Query Param	code	Token: The type of observation (LOINC Code). e.g., `code=http://loinc.org	8310-5`
Query Param	date	Date: Date range search. e.g., date=ge2023-01-01&date=le2023-12-31	Optional

1.4 Return Variables and their Types or Structures #

A. Success Response for Create/Read/Update #

Status Code	Response Type	Key Fields	Description
200 OK (Read/Update)	Single FHIR Resource	id, meta.versionId, resourceType, clinical data fields.	Success retrieval or modification.
201 Created (Create)	Single FHIR Resource	id, meta.versionId, resourceType, clinical data fields.	Success creation.

B. Success Response for Search #

Status Code	Response Type	Key Fields	Description
200 OK	FHIR Bundle	resourceType (“Bundle”), type (“searchset”), total (Number), entry (Array).	Contains the list of matching FHIR resources.

Example Search Response Body:

{
“resourceType”: “Bundle”,
“type”: “searchset”,
“total”: 2,
“entry”: [
{
“resource”: {
“resourceType”: “Observation”,
“id”: “obs-1”,
“code”: {
“coding”: [{
“system”: “[http://loinc.org](http://loinc.org)”,
“code”: “8310-5”,
“display”: “Body temperature”
}]
},
“valueQuantity”: {
“value”: 38.1,
“unit”: “C”,
“system”: “[http://unitsofmeasure.org](http://unitsofmeasure.org)”
}
}
}
]
}

1.5 Exceptions and Exception Handling Methods #

The API uses standard HTTP status codes and FHIR OperationOutcome resources for detailed error reporting.

HTTP Code	Cause	Response Body	Handling Method
400 Bad Request	Invalid request syntax, malformed JSON, or unknown search parameter.	FHIR OperationOutcome (details text).	Parse OperationOutcome for client-side fix (e.g., parameter correction).
401 Unauthorized	Missing or invalid AWS Signature (SigV4).	AWS Plain Text/Simple JSON error message.	Re-authenticate, check AWS credentials and signature logic.
403 Forbidden	IAM user lacks necessary permissions.	AWS error message.	Check IAM role policies and HealthLake permissions.
404 Not Found	Resource not found or invalid Data Store ID in URL.	FHIR OperationOutcome.	Client logs the issue; potentially displays a ‘Resource Not Found’ message.
422 Unprocessable Entity	Business rule violation (e.g., duplicate identifier).	FHIR OperationOutcome (code: “duplicate”).	Client must correct the resource data before retrying the request.
429 Too Many Requests	Exceeded the API rate limits.	AWS throttling message.	Client must implement retry logic with exponential backoff.
500 Internal Server Error	Unexpected server error.	Generic error message.	Client should retry the request after a short delay.

Example 400 OperationOutcome:

{
“resourceType”: “OperationOutcome”,
“issue”: [{
“severity”: “error”,
“code”: “invalid”,
“details”: {
“text”: “Invalid search parameter ‘birthdate’. Did you mean ‘birthdate’?”
}
}]
}

Section 2: API Implementation Requirements #

To successfully interact with the AWS Healthlake FHIR API, a client application must implement the following components and configurations:

2.1 Authentication & Authorization (AWS Signature Version 4) #

Requirement	Component / Configuration	Detail
SigV4 Generator	HTTP client library or AWS SDK (e.g., Boto3, Java SDK).	Must generate a valid AWS Signature Version 4 for signing requests.
AWS Credentials	Valid AWS Access Key ID and Secret Access Key.	Credentials must be associated with an IAM user/role granted required permissions (e.g., HealthLake:ReadResource).
Region Targeting	Configuration setting.	Must target the correct AWS Region (us-east-1).

2.2 FHIR RESTful Endpoint & Security #

Requirement	Component / Configuration	Detail
Secure Client	Standard HTTP/S client.	Required for all communication.
Base URL Configuration	Exact Data Store endpoint.	https://healthlake.us-east-1.amazonaws.com/datastore/8d8ae0ebc52744d8d9c6af8009bef7e6/r4/
Transport Layer Security	Client must enforce TLS 1.2 or higher.	Ensures secure communication of PHI in transit.

2.3 FHIR Standard Compliance #

Requirement	Component / Configuration	Detail
Data Models	Application classes or structures.	Must represent FHIR R4 resources (e.g., Patient, Observation) for reliable data processing.
Serialization	Robust JSON library.	Required to serialize request bodies into FHIR JSON and deserialize response bodies into usable objects.
Bundle Handling	Application logic.	Must implement logic to process transaction batches and parse search set responses returned as FHIR Bundle resources.

2.4 Error Handling & Resilience #

Requirement	Component / Configuration	Detail
Error Handling Logic	Application logic.	Must handle standard HTTP errors (401, 403, 404, 422).
OperationOutcome Parsing	Application logic.	Must parse the OperationOutcome FHIR resource in 4xx error responses to provide meaningful diagnostic information.
Retry Logic	Configuration/Algorithm.	Must implement retry logic with exponential backoff for 5xx server errors and throttling responses (429 Too Many Requests).

Section 3: API’s Terms of Use #

General Overview #

Use of the AWS HealthLake FHIR API is governed by the terms of the AWS Service Agreement, the HIPAA Business Associate Addendum (BAA), and the organization’s internal data-sharing policies. All API consumers must agree to the following terms before gaining access.

Developer Access and Registration #

• Registration: Developers must register through the LegendEHR Developer Portal or AWS Identity Management console to obtain necessary credentials (e.g., AWS Access Keys).
• Authorization Scopes: Each registered application will be assigned specific authorization scopes (e.g., system/Patient.read, system/Observation.write). Access is strictly controlled by these scopes.

Permitted Use #

• Authorized Use: The API may be used solely for authorized healthcare operations, treatment, payment, or healthcare management purposes consistent with HIPAA.
• Consent: Applications must use the API only to access EHI for patients or organizations with appropriate authorization and consent.

Prohibited Use #

• Data Misuse: API access may not be used to scrape, resell, or redistribute EHI data.
• Data Mining: Applications must not use API access to infer sensitive information or engage in data mining outside approved purposes.
• Reverse Engineering: Reverse engineering or unauthorized modification of the API infrastructure is strictly prohibited.

Data Security #

• Encryption: All data accessed or stored via the API must be encrypted at rest and in transit (enforced via HTTPS/TLS 1.2+).
• Credential Storage: Access tokens and credentials must be stored securely and never embedded in client-side code.
• Incident Reporting: Any security incident or data breach must be reported immediately to the system administrator and AWS Security.

Service Limits and Compliance #

• Rate Limits: AWS may throttle or limit request rates to ensure fair use and protect performance. Clients must adhere to these limits.
• Access Revocation: System administrators may revoke access if misuse, noncompliance, or a security concern is detected.
• Compliance Mandate: Developers must comply with all applicable federal, state, and local laws, including HIPAA, HITECH, and the 21st Century Cures Act. Use of the API signifies agreement to adhere to ONC 170.315 (g)(9) and (g)(10) access standards.

Support and Contact #

• Developer Support: For developer support, documentation, and registration, contact: support@legendehr.com