13.0FHIR Gateway Endpoint
The FHIR Gateway Endpoint module creates a FHIR server that acts as a proxy for another FHIR server.
The high level architecture is shown in the following diagram.
Purpose
Although the third-party FHIR server can be another Smile CDR instance, it does not need to be. This proxy can serve several purposes in a solution architecture.
- The gateway uses the standard Smile CDR security modules, meaning that the endpoint can be authorized with permissions authorized from your user database, or SMART-on-FHIR enabled, or have features selectively disabled. This system also provides auditing on all access and modifications to data.
- The gateway rewrites links and headers within the returned content, preventing end users from learning internal implementation details of the complete solution.
- The gateway can add standard FHIR REST capabilities to the endpoint, such as validation, CORS support, etc.
- The gateway will automatically convert content between supported FHIR encoding formats, even if the backing server only supports a single encoding (e.g. XML or JSON).
- The gateway can optionally cache search results allowing results to be paged for the client even if the third party system does not support result paging.
13.0.1Gateway Architecture
The FHIR Gateway Endpoint forwards incoming requests to a third-party FHIR server known as the Target Server.
During the module startup, the FHIR Gateway Endpoint module queries the target server to analyze its conformance statement (using the FHIR capabilities operation).
This operation is crucial to the operation of the gateway: If the target server does not correctly generate a Capability Statement, the FHIR Gateway Endpoint module will fail to start. If the target server goes not describe a particular resource type or operation, that resource type or operation will not be available through the gateway.
Once the gateway is started, client requests are accepted and processed. Where necessary, they are forwarded to the target server for processing.
The following diagram shows the startup and operation of the module.
13.0.2Creating a FHIR Gateway Endpoint
When creating a FHIR Gateway Endpoint module, the following configuration items are required:
-
The FHIR Gateway Target configures the client connection from the gateway to the target server. Most importantly, a FHIR version and Base URL should be set. Optionally, credentials and other details may also be set.
-
The Database section provides a database that is used for temporary local storage for the gateway. This can use the same schema that is used by the Cluster Manager database in a simple deployment, but it is generally preferable to create a dedicated schema for this purpose.
-
The HTTP Listener section provides the details for the listening server on the gateway itself. This defines the port and other details for the server in Smile CDR that clients will connect to.
13.0.3Invoking Operations
FHIR Operations can be invoked on the target server, including custom operations (operations that are not defined in the core FHIR specification).
Note that special care should be taken when designing a security architecture if operations are enabled. Smile CDR permissions should be used to authotize users to invoke operations, but simple permissions may not always be sufficient: If an operation involved modifying or accessing sensitive/secure information, it may not be possible for Smile CDR to know this simply by examining the URL and method details.
For example, consider the $render operation on the QuestionnaireResponse. This operation returns a rendered view of a QuestionnaireResponse. If a given user only has access to read resources from a specific Patient compartment, then this user should not be able to see all rendered QuestionnaireResponse instances. However, when this operation is invoked, it is not possible for Smile CDR to determine the subject of the QuestionnaireResponse simply by examining the OperationOutcome response. This should be considered when setting up such an infrastructure.
13.0.4Request/Response Translation
The Gateway will typically favor the FHIR encoding used by the target server when it returns its CapabilityStatement. For example, if the server returns a JSON CapabilityStatement, the Gateway will prefer the use of JSON even when the client calling the Gateway is using XML encoding. In this case, the JSON response from the target server will be converted to XML before being returned to the calling client.
If the client requests a non-FHIR response (via an Accept header in the request), the Accept value will be passed verbatim to the target server.
A Simple Example
The following configuration defines a simple gateway that uses an in-memory embedded H2 database and proxies requests from port 8000 to a target server on port 8200.
module.fhir_gateway.type =ENDPOINT_FHIR_GATEWAY
module.fhir_gateway.requires.CLUSTERMGR =clustermgr
module.fhir_gateway.requires.SECURITY_IN_UP =local_security
module.fhir_gateway.config.port =8000
module.fhir_gateway.config.security.http.basic.enabled =true
module.fhir_gateway.config.target_server.fhir_version =DSTU3
module.fhir_gateway.config.target_server.base_url =http://localhost:8200
module.fhir_gateway.config.db.url =jdbc:h2:file:./database/h2_gateway_database
module.fhir_gateway.config.db.driver =H2_EMBEDDED
module.fhir_gateway.config.db.username =SA
module.fhir_gateway.config.db.password =SA
The HAPI FHIR CLI could be used to serve a target server for testing using the following command:
./hapi-fhir-cli run-server -v dstu3 -p 8200