13.1.1FHIR Endpoint Module

The FHIR Endpoint module is an HTTP Server (i.e. a web server) that allows external clients to interact with the FHIR Storage module.

13.1.2Creating the Module

When creating a FHIR Endpoint module, you must first choose which version of FHIR it will support. There are multiple types of FHIR Endpoint modules, and each one supports a specific version of FHIR. The version of FHIR must match the version of FHIR supported by the FHIR Storage module.

13.1.2.1Server Configuration

There are only a few settings that absolutely must be set when creating this module:

• Port – The port that the server will listen on (e.g. 8000).
• Fixed Value for Endpoint Base URL – Tells the server what it should advertise as the FHIR base URL (e.g. http://acme.org:8000).
• Dependency FHIR Persistence: This is a reference to the FHIR Storage module that backs this endpoint.

13.1.3Request Transaction IDs

For every HTTP request received by a FHIR Endpoint module, two identifiers are generated:

The Request ID may be supplied by the client using the X-Request-ID HTTP request header (see Capturing Source Information below). If the client does not supply a Request ID, an ID will be automatically generated by the HTTP server and associated with the request. Generated IDs are 16 character alphanumeric strings. These automatically generated tokens are intended for easy lookup and must not be treated as cryptographically secure (i.e. they may be guessed).

Whether it was supplied by the client or generated by the server, the Request ID will be returned in HTTP responses in a corresponding X-Request-ID HTTP response header. This makes it a good candidate for participating in distributed monitoring applications.

The request ID is stored in the Audit Log and Transaction Log. Past Request ID values may be used as a search parameter when searching the Transaction Log.

The request ID is stored in the Audit Log and Transaction Log. Past Transaction GUID values may be used as a search parameter when searching the Audit Log.

If enabled, the Transaction GUID can be added to returned resources through Response Watermarking.

13.1.4Capturing Source Information

When processing incoming resources (i.e. for create, update, etc.) some basic details about the resource provenance are captured in Resource.meta.source. Smile CDR stores both the Source System URI (typically the identity of the system that was used to create the data) as well as the Transaction ID (typically a unique identifier for the specific HTTP request involved).

When Smile CDR is storing FHIR data (using a FHIR Storage module) these two fields are automatically combined using a hash symbol. For example, given a Source System URI of http://example.com/some-app and a Transaction ID of 000001 the system might capture the following value:

{
  "resourceType": "Patient",
  "meta": {
    "source": "http://example.com/some-app#000001"
  }
}

It is possible to supply both of these properties using HTTP Request Headers in environments where it is easier to capture/inject this data using network infrastructure. The following two headers may be used:

• X-Request-ID – Supplies the Transaction ID.
• X-Request-System – Supplies the Source System ID. The process_request_header.request_source_enabled property must be enabled on the module in order to use this header.

13.1.4.1Searching

See Storing Source Information for information on how this information is stored and how it can be used for searching.

13.1.5Response Watermarking

If the Response Watermarking setting is enabled on FHIR Endpoint modules, any FHIR resources returned by the endpoint will automatically have a watermark string containing the associated Transaction GUID and several other values injected in an extension in the resource Meta element.

This feature allows for after-the-fact correlation between resources stored on other systems, and the original Smile CDR transaction that was used to retrieve them. This can be helpful in investigations, although it is important to remember its limitations:

• Watermarks are not tamper-proof: A client can easily remove or modify the watermark prior to storage.
• Watermarks are only added to the response to basic HTTP FHIR read interactions (read/search/history). Other mechanisms such as batch, transaction, and $operations are not watermarked.
• If the response is a search Bundle, each resource in the Bundle will have a watermark added, and the Bundle itself will have one as well. Contained/inline resources (resources found specifically within the contained element in a resource) are not watermarked.

The watermark string is a Base64 encoded string containing the following information:

• The transaction GUID associated with the request used to access the resource (not the transaction used to create it).
• The fully qualified resource URL including the server base URL.
• The current timestamp.

A simple example resource containing a watermark is shown below:

{
  "resourceType": "Patient",
  "id": "A",
  "meta": {
    "extension": [ {
        "url": "https://smilecdr.com/fhir/ns/StructureDefinition/resource-transaction-id",
         "valueString": "OTdmMzU1ZWItNzZhMS00NDk3LTkyODctZmFjMzFmNTlkZDFmCmh0dHA6Ly9sb2NhbGhvc3Q6NTYxMDIvUGF0aWVudC9BL19oaXN0b3J5LzEKMjAyMy0wNy0yM1QxNTo0NTo0NC41NzktMDQ6MDA="
    } ],
    "versionId": "1"
  },
  "active": true
}

13.1.6Validation

You can configure a FHIR endpoint to validate resources as they enter or leave the system (i.e. request and response payloads). See Endpoint Validation for information.

13.1.7Configuration

13.1.7.1Reference

A complete reference of configuration items follows: