Standardized API for Patient and Population Services #

Overview #

LegendEHR provides standardized FHIR-based RESTful APIs to enable third-party applications and authorized users to securely access and exchange Electronic Health Information (EHI).
The implementation uses AWS HealthLake as the backend FHIR datastore, conforming to HL7® FHIR® Release 4 (R4) and SMART on FHIR standards for interoperability, authorization, and data security.

All API interactions occur via HTTPS (TLS 1.2 or higher) and use OAuth 2.0 authorization managed through AWS Cognito.

1. API Syntax #

All API requests follow the RESTful pattern defined by HL7 FHIR:

[resourceType]/[id]?[parameters]

Base URL (FHIR endpoint):

https://healthlake.us-east-1.amazonaws.com/.healthlake.amazonaws.com/datastore/8d8ae0ebc52744d8d9c6af8009bef7e6/r4

 

Example:

https://healthlake.us-east-1.amazonaws.com/.healthlake.amazonaws.com/datastore/8d8ae0ebc52744d8d9c6af8009bef7e6/r4/Patient?name=John

2. Supported FHIR Resource Endpoints #

Function Name	HTTP Method	Description
/Patient	GET	Retrieve a list of patients or search by parameters
/Patient/{id}	GET	Retrieve a specific patient resource
/Observation	GET	Retrieve laboratory results, vitals, or clinical observations
/Condition	GET	Retrieve problem/diagnosis lists
/Encounter	GET	Retrieve clinical encounter or visit records
/MedicationRequest	GET	Retrieve medication prescription records
/Appointment	GET	Retrieve patient appointment data
/$export	POST	Initiate population-level export (FHIR Bulk Data Access)

3. Required and Optional Parameters #

Parameter	Required	Type	Description
id	Yes (for specific resource requests)	String	Unique FHIR resource ID
_count	No	Integer	Limit the number of results per page
_since	No	DateTime	Retrieve data updated since a given date
patient	No	String	Filter results for a specific patient
category	No	String	Filter observations by category
status	No	String	Filter conditions or encounters by status

All parameters follow FHIR R4 REST API conventions.

 

4. Response Format #

All responses are returned as FHIR JSON resources.
Each resource includes a resourceType attribute and conforms to HL7 FHIR R4 schema.

Example – GET /Patient/{id}:

{

  “resourceType”: “Patient”,

  “id”: “12345”,

  “name”: [{ “given”: [“John”], “family”: “Doe” }],

  “gender”: “male”,

  “birthDate”: “1980-05-15”

}

 

Example – GET /Observation:

{

  “resourceType”: “Observation”,

  “id”: “obs001”,

  “status”: “final”,

  “code”: { “text”: “Heart rate” },

  “valueQuantity”: { “value”: 72, “unit”: “beats/minute” }

}

5. Exceptions and Error Handling #

The API follows FHIR standard OperationOutcome responses for errors.

HTTP Status	Meaning	Response Behavior
400	Bad Request	Invalid or missing parameters
401	Unauthorized	Token missing or invalid
403	Forbidden	User lacks access rights
404	Not Found	Resource unavailable
500	Server Error	Internal system error

Example Error Response:

{

  “resourceType”: “OperationOutcome”,

  “issue”: [

    {

      “severity”: “error”,

      “code”: “invalid”,

      “diagnostics”: “Invalid query parameter value.”

    }

  ]

}

6. Software Components and Configuration Requirements #

To successfully connect and process responses, client applications must support:

• FHIR R4 JSON serialization

• HTTP/HTTPS REST operations (GET, POST, PUT, DELETE)

• OAuth 2.0 authorization (SMART on FHIR profile)

• TLS 1.2 or higher

Mandatory configurations:

• Application registered with the AWS Cognito Authorization Server

Authorization header with Bearer token:

Authorization: Bearer <access_token>

 

7. Application Registration Process #

Third-party applications must register with the LegendEHR authorization server to obtain access tokens.

Required Registration Information:

• Client ID

• Client Secret

• Redirect URI

• Client Type (Public / Confidential)

• Requested Scopes (launch, openid, profile, patient/*.read, user/*.read)

• Grant Type: authorization_code or client_credentials

Authorization Server Details #

Authorization Server URL:

https://healthlakeoauth.auth.us-east-1.amazoncognito.com

 

SMART on FHIR Discovery Endpoints:

• https://healthlake.us-east-1.amazonaws.com/datastore/8d8ae0ebc52744d8d9c6af8009bef7e6/r4/.well-known/smart-configuration
• https://healthlake.us-east-1.amazonaws.com/datastore/8d8ae0ebc52744d8d9c6af8009bef7e6/r4/metadata

These endpoints define the supported scopes, grant types, and capabilities required for ONC §170.315(g)(10) compliance.

8. Security and TLS Enforcement #

All API connections are encrypted using TLS 1.2 or higher.
The LegendEHR API does not permit or support any connections below TLS 1.2.
This enforcement aligns with NIST SP 800-52 Rev. 2 and ONC Health IT Certification standards.

No additional documentation is required for lower TLS versions as they are not supported or implemented.

9. Bulk Data and Population-Level Access #

The API supports the FHIR Bulk Data Access (“Flat FHIR”) specification for population-level exports.

Endpoint:

POST [baseURL]/$export

 

Supported Parameters:

• _type – Specify resource types to export

• _since – Export data updated since a given timestamp

• _outputFormat – Defaults to application/fhir+ndjson

Example Request:

POST https://<your-base-url>/$export

Authorization: Bearer <access_token>

Accept: application/fhir+json

 

10. Developer Support and Access Policy #

LegendEHR provides open, standardized API documentation to promote interoperability and innovation.
This documentation and endpoints are publicly accessible for developers, implementers, and ONC certification testers.

Developers can:

• Access the documentation at any time without preconditions

• Create an account (if required) through an automatically approved registration process

• Obtain test credentials via the developer portal to connect and validate API access

Developer Contact:
support@legendehr.com