FHIR R4 Directory Rollout

New HAPI directories have been available since 4/12/2023

Email techsupport@ehealthexchange.org to get access to the new HAPI directories:
 
  • For existing FHIR API users, ask to have your API key migrated to the HAPI directories.  You can continue to access the legacy directories, as needed.
  • For organizations that have not accessed the directory FHR API in the past, ask for a new FHIR API key to access the HAPI directories.
Email techsupport@ehealthexchange.org for directory endpoint URLs and API options.
 
Provide feedback on the new HAPI directories:
 

New HAPI Directory – FHIR Implementation Guides (IGs)

The Base FHIR R4 IG and eHealth Exchange FHIR R4 IG are at the bottom of the technical specifications page under the Directory Implementation Guides section.  Navigate to:
 
 
There is no IG documentation for the STU3 API for the new FHIR directories which documents FHIR capabilities such as search parameters, read operations, etc. The STU3 API under the new FHIR directories generally conforms to the HL7 FHIR R4 capabilities listed below, as it’s an API into a FHIR R4 directory.
 

New HAPI Directory APIs – 3 API Choices But Only 2 APIs by Summer 2024

FHIR Client API

Access the directory with a FHIR client using a FHIR API key provided by Sequoia technical support – email techsupport@ehealthexchange.org for a FHIR API key
 
  • Provides access to both Argonaut STU3 FHIR (same as the current directory offering) and FHIR R4 APIs
  • Typically provides read-only access – no update or create operations

UDDI API (SOAP API) to be retired by 8/16/2024

  • The new FHIR HAPI based directory will support a traditional UDDI/SOAP interface. Newer data elements introduced with STU3/R4 will not be available under the UDDI/SOAP interface.
  • No access to sub-participant entries.
  • Access will require SSL/TLS certificate-based security only and requires trust of DirectTrust CAs such as EMR Direct and MaxMD, as in the past.
  • The UDDI API will be retired on 8/16/2024, so make plans to migrate to the FHIR R4 API.

New HAPI Directories and Hub Endpoints

FHIR Client API and Hub endpoints

Unlike the current directories, using the FHIR APIs, there are no longer separate directories for direct endpoints and Hub endpoints.
 
To obtain Hub endpoints using the FHIR APIs, use the FHIR operation $hub-aware.  For example:
 

UDDI API (SOAP API) and Hub endpoints [UDDI API to be retired 8/16/2024]

The base URI remains the same for direct and Hub endpoints but the path changes.  For example:
 

Directory Endpoint Options

Note: Email techsupport@ehealthexchange.org for the proper “VAL-HOSTNAME”

FHIR R4 API

  • Direct endpoints: https://VAL-HOSTNAME/fhir/Organization?_apiKey=<INSERT_API_KEY>&_format=json
  • Hub endpoints: https://VAL-HOSTNAME/fhir/Organization/$hub-aware?_apiKey=<INSERT_API_KEY>&_format=json

Argonaut STU3 API

  • Direct endpoints: https://VAL-HOSTNAME/fhir-pre-stu3/Organization?_apiKey=<INSERT_API_KEY>&_format=xml
  • Hub endpoints: https://VAL-HOSTNAME/fhir-pre-stu3/Organization/$hub-aware?_apiKey=<INSERT_API_KEY>&_format=xml

UDDI API [not available after 8/16/2024]

  • Direct endpoints: https://VAL-HOSTNAME/uddi
  • Hub endpoints: https://VAL-HOSTNAME/uddi-hubaware

PRODUCTION DIRECTORY

Note: Email techsupport@ehealthexchange.org for the proper “PROD-HOSTNAME”

FHIR R4 API

  • Direct endpoints: https://PROD-HOSTNAME/fhir/Organization?_apiKey=<INSERT_API_KEY>&_format=json
  • Hub endpoints: https://PROD-HOSTNAME/fhir/Organization/$hub-aware?_apiKey=<INSERT_API_KEY>&_format=json

Argonaut STU3 API

  • Direct endpoints: https://PROD-HOSTNAME/fhir-pre-stu3/Organization?_apiKey=<INSERT_API_KEY>&_format=xml
  • Hub endpoints: https://PROD-HOSTNAME/fhir-pre-stu3/Organization/$hub-aware?_apiKey=<INSERT_API_KEY>&_format=xml

UDDI API [not available after 8/16/2024]

  • Direct endpoints: https://PROD-HOSTNAME/uddi
  • Hub endpoints: https://PROD-HOSTNAME/uddi-hubaware

Change in Functionality – Inactivated Entries Are Now Logically Deleted

With the legacy directories, when a directory entry is inactivated and should no longer be consumed, we set the “active” element to false.
With the new HAPI directories, the following is done instead:
  • The “active” element set to false now indicates that a directory entry is pending eHealth Exchange approval.  An “active=false” entry should not be consumed by directory clients as it has not been approved.
  • When a directory entry is removed from the HAPI directories, it will be logically deleted using HTTP DELETE and can no longer be found using a directory search for Organization entries.
  • Logically deleted entries can be discovered by querying with a $status-changes operation, with an optional date range and “deleted=true” parameter.
  • If the “deleted=true” option is used, then results will only be returned if the last state of a directory entry is deleted within the timeframe specified by the query.  For example:
    • If a directory entry is not deleted on 3/1, is deleted on 3/15 and is re-activated on 3/20:
      • The directory entry will be included in the results if the end date for the query is 3/16.
      • If the end date for the query is 3/21, then it will not be included in the results, because the entry was re-activated and is no longer deleted within that timeframe.
  • A simple FHIR R4 search query example using $status-changes is: https://VAL-HOSTNAME/fhir/Organization/$status-changes
  • A FHIR R4 search query that uses $status-changes with a timeframe and the “deleted=true” option: https://VAL-HOSTNAME/fhir/Organization/$status-changes?deleted=true&start=2023-03-01T20:00:00&end=2023-03-16T23:59:59
  • •The response to the $status-changes query is a FHIR List.  An example of the response content is below: 
    • As per the example, the code of “deprecate” indicates the entry has been deleted.
    • The XPath for the HCID of the deleted entry is: /List/entry/item/identifier/value/@value

Directory Query Recommendations

Directory entries with “active=false” are unapproved and not ready to query.

Unlike the legacy directories, if you don’t specify a value for “active“, then the default is not “active=true”.  Entries will be returned with active set to true and false if the active parameter is not specified.

Query parameter/value for Participant entries: type=https://sequoiaproject.org/fhir/sphd/CodeSystem/OrganizationType%7C
Participant
  • Note: %7C is an URL encoded pipe character (“|”)
In the future, the directory will have Subparticipant entries which represent provider locations such as a hospital or clinic. Subparticipant entries are not expected to have endpoints in the short-term.
HAPI has a paging feature which adheres to the paging behavior specified by FHIR R4 – see http://hl7.org/fhir/R4/search.html#count
 
The directory is currently set to a default page size of 500, so by default, 500 records will be returned for a single response. You can return less records in a response by setting the _count parameter to a value lower than 500.
 
The maximum page size is 23,000, so you cannot increase the page size beyond 23,000 using the _count parameter. The maximum page size will be lowered in the future to a lower value now that directory paging issues have been resolved.

Rollout of New HAPI Directories and Retirement of Legacy Directories

  • The legacy directories were retired on July 27, 2023, and are no longer accessible by participants.
  • The eHealth Exchange has been forwarding requests from the retired legacy directories to the new HAPI directories since August 10, 2023. Directory request forwarding was documented in detail during the August 2023 all participant call and the slides are accessible under eHealth Exchange Communications.
  • The eHealth Exchange is aware of several participants that need to use the endpoints for the HAPI directories and not rely on directory forwarding. If you are not certain whether your organization is using the endpoints of the HAPI-based directories for FHIR R4 content and/or are concerned you may be relying on forwarding from the retired legacy directories to the new HAPI-based directories, please send an inquiry to administrator@ehealthexchange.org.