Hybrid / Intermediary Exchange
0.1.0 - STU 1 Ballot
Hybrid / Intermediary Exchange
0.1.0 - STU 1 Ballot
This page is part of the Hybrid / Intermediary Exchange (v0.1.0: STU1 Ballot 1) based on FHIR R4. The current version which supercedes this version is 1.0.0. For a full list of available versions, see the Directory of published versions 
This section further describes details of the scenarios introduced in the Use Cases and Roles section, and specifies approaches for “addressing” exchanges between the originating system, participating intermediaries and the ultimate destination system.
This guide assumes that the destination and intermediary participants have established business arrangements, if required, and performed configuration activities, if required, prior to processing requests. These SHALL include the following, but MAY include the setup of additional value-add services performed by the intermediary participants.
To support the routing approaches described in this guide, the destination SHALL have a single, public FHIR service base URL for each FHIR service it makes available.
The partnering destination and inbound gateway intermediary are free to determine the appropriate structure of the public FHIR service base URL to meet their preferences and technical requirements. For example, the URL’s hostname may refer to either the destination or the intermediary and path segments may be included to identify the destination, specify the supported FHIR version, etc. In addition, the destination SHALL reference its public URL in returned FHIR resources.
Example approaches:
fhir.example-intermediary.com/example-destination. In this method, the destination’s public FHIR service URL consists of a base URL reflecting the inbound gateway Intermediary’s identity followed by a path segment following the base that reflects the destination’s identity. The intermediary may then base routing on the path segment that indicates the destination.fhir.example-destination.com. In this method, the destination uses a public FHIR service base URL that reflects its own identity and, in turn, hides participation of the inbound gateway Intermediary it employs. The intermediary bases routing on the network IP address at which it receives the request (the IP to which the public URL’s DNS record is mapped).example-destination.example-intermediary.com. In this method, the destination is represented using a subdomain of the inbound gateway Intermediary’s URL. The intermediary bases routing on the network IP address to which the subdomain’s DNS record is mapped.This guide does not prescribe a particular URL structure to be used; however, it SHALL be a valid FHIR service base URL that originators can use without knowledge of its individual components–as they do any other FHIR service URL
This implementation guide does not support URL rewriting, based on stakeholder input regarding the difficulty of reliably locating and adjusting applicable URLs, and the complexity it introduces to security aspects such as signing payload content. It may be considered in future enhancements to the IG.
The destination and each delegated intermediary (participating in exchange hops following the inbound gateway intermediary) defines the URL at which it accepts requests intended for the destination. Each party is free to determine the appropriate structure of the URL to meet its preferences and technical requirements, as described in the preceding section.
This guide does not prescribe a particular URL structure to be used; however, it SHALL:
“Private” FHIR service base URLs are shared between participating parties as needed to facilitate routing during the exchange. This guide does not assume that a participant will be aware of the URLs used by all “hops” in the exchange, but only its own URL and that of the next participant to which it forwards a request.
References to the destination’s server in FHIR resources that it produces SHALL equal the destination’s single public FHIR service base address.
For example, the Bundle.entry.fullUrl element for a resource on the destination’s server SHALL contain the same FHIR service base address as the destination would publish in a public endpoint directory.
In this exchange model, trust has been established or is negotiated solely between the originator and destination. It is the destination which makes the decision as to whether it trusts the originator or not; any intermediaries involved in the exchange play a passive, “pass through” role in the process.
Required behavior:
See the Security section for additional details.
The required behavior described above for single-intermediary scenarios apply equally when one or more additional intermediaries participate in the exchange, as illustrated below.
This initial release of the Hybrid/Intermediary Exchange IG focuses on a range of typical intermediary routing scenarios in which exchange happens over the public internet using RESTful interactions, originators address requests directly to destinations' public FHIR service URLs, and authentication and authorization are negotiated between the originator and ultimate destination. Additional scenarios and environments may be addressed in future enhancements to the IG.
Based on the rules and constraints described above, the following underscores scenarios that are not in scope of this implementation guide.
This scenario supports a situation where the destination delegates the responsibility of securing a public endpoint–and potentially performing other functions such as registering clients–to an intermediary. A single intermediary participates in this exchange, forwarding requests directly from the originator to the destination.
Below is the main flow of this scenario.
Step 1. Originator obtains the destination’s public FHIR service address
Before the exchange, the originator system obtains the destination’s public FHIR service address, for example through a reference in a previously-received FHIR resource or by consulting an endpoint directory.
Step 2. Originator initiates a RESTful interaction using the destination’s public FHIR service address
The originator system then initiates a RESTful exchange (for example, a GET method to retrieve a FHIR resource) that is transmitted to the destination’s public FHIR service address.
Step 3. The exchange is received by the inbound gateway intermediary
The intermediary receives the request on behalf of the destination. The sections below describe multiple approaches for constructing the destination’s public FHIR service address, but in all cases its URL resolves to a destination-specific location at the intermediary.
Step 4. The intermediary routes the exchange to the destination
The intermediary determines where to route the exchange based on its arrangement with the destination owner.
Because the destination’s public URL resolves to a destination-specific location at the intermediary–the intermediary can recognize the intended receiver and determine the correct routing to that destination.
Step 5. The destination processes the request and returns its response to the intermediary
The destination processes the request and synchronously returns its response.
Note that any references to the destination’s FHIR service in resources that are returned by the destination–for example, in a search result Bundle’s fullUrl element–SHALL be populated by the destination server to match the public FHIR service address used by the originator.
Step 6. The intermediary passes through the response to the originator
The intermediary, which is holding a synchronous connection with the originator, passes through the response.
Step 7. The originator receives the response
The originator accepts the response. If it wishes to submit a follow-on request using a reference in a received resource, it interprets the reference as typically does, without any adjustments caused by the initial request having been routed through an intermediary. This is possible because the destination uses its public FHIR address as the FHIR service base value in elements such as Bundle.fullUrl.
Exchange flow
Example - Intermediary’s Base URL followed by a path indicating the destination
This scenario supports a situation where one or more additional “delegated” intermediaries–beyond the inbound gateway with with the originator directly interacts–is used to deliver a request to its ultimate destination.
Below is the main flow of this scenario.
Step 1. Originator obtains the destination’s public FHIR service address1000
Step 2. Originator initiates a RESTful interaction using the destination’s public FHIR service address
Step 3. The exchange is received by the inbound gateway intermediary
The initial steps in this scenario are the same as in the one-intermediary scenario above–the originator submits its request to the public FHIR service address for the destination, which is received by the inbound gateway intermediary to be routed onward.
Step 4. The inbound gateway intermediary routes the exchange to a second intermediary
The intermediary forwards the exchange to a second “delegated” intermediary who will forward it on toward the destination organization.
This determination is based on arrangements previously established between this intermediary, the destination owner and/or participating intermediaries.
Note: This implementation guide does not prescribe the nature of such arrangements nor the manner by which intermediaries discover or represent them within their systems.
Step 5. The second intermediary routes the exchange to the destination endpoint
Based on routing metadata conveyed to it in the URL path or via HTTP headers, the second intermediary determines where to route the exchange based on its arrangement with the inbound gateway intermediary and/or the destination owner.
Step 6. The destination processes the request and returns its response to the intermediary
The destination processes the request and synchronously returns its response.
Note that any references to the destination’s FHIR service in resources that are returned by the destination–for example, in a search result Bundle’s fullUrl element–SHALL be populated by the destination server to match the public FHIR service address used by the originator.
Step 7. The second intermediary passes through the response to the inbound gateway intermediary
The intermediary, which is holding a synchronous connection with the originator, passes through the response
Step 8. The inbound gateway intermediary passes through the response to the originator
The intermediary, which is holding a synchronous connection with the originator, passes through the response.
Step 9. The originator receives the response
The originator accepts the response. If it wishes to submit a follow-on request using a reference in a received resource, it interprets the reference as typically does, without any adjustments caused by the initial request having been routed through an intermediary. This is possible because the destination uses its public FHIR address as the FHIR service base value in elements such as Bundle.fullUrl.
Exchange Flow
Example - Intermediary’s Base URL followed by a path indicating the destination
In this scenario, the originator uses the FHIR Asynchronous Pattern to retrieve data from a destination that uses an inbound gateway intermediary as described above.
Below is the main flow of this scenario.
Step 1. Originator obtains the destination’s public FHIR service address
Step 2. Originator initiates a RESTful interaction using the destination’s public FHIR service address
In this scenario, the originator populates the Prefer HTTP header with respond-async to notify the destination that it want to obtain the response data asynchronously.
Step 3. The exchange is received by the inbound gateway intermediary
Step 4. The intermediary routes the exchange to the destination
The Prefer: respond-async header is also forwarded to the destination.
Step 5. The destination processes the request and returns its response to the intermediary
The destination responds with an HTTP status code of 202 Accepted, and an HTTP header containing a Content-Location parameter that specifies the URL at which the response data will be available.
The Content-Location base SHALL be populated by the destination to match the public FHIR service address used by the originator.
Step 6. The intermediary passes through the response to the originator
The intermediary, which is holding a synchronous connection with the originator, passes through the response.
Step 7. The originator receives the response
The originator accepts the response.
Step 8. The originator later retrieves the response data
The originator later retrieves the response data using the address previously returned in the Content-Location parameter of the initial response from the destination. This request and response are routed as described in Steps 1-7, except that the Prefer: respond-async parameter is not used.
Exchange Flow
Example - Intermediary’s Base URL followed by a path indicating the destination
IG © 2021+ HL7 International - FHIR Infrastructure. Package hl7.fhir.us.exchange-routing#0.1.0 based on FHIR 4.0.1. Generated 2021-12-03
Links: Table of Contents |
QA Report
| Version History |
Search |
|
Propose a change