Caching

The FHIR Gateway includes a cache which can be used to avoid duplicate calls to the target servers when repeated identical invocations are made to the gateway in short succession, and in some cases can be used to buffer subsequent pages of search results.

To enable the cache, set the Pagination Cache Provider to either CAFFEINE (for a local in-memory cache), or INFINISPAN (for a remote networked cache). To disable the cache, a value of NONE can be used (this is the default).

This cache currently has the following properties, and it may be enhanced in the future:

• FHIR Search (including subsequent page requests), FHIR Read/VRead operations, and invocations of the FHIR Operations listed in Cacheable Operations are cached. No other actions are cached.
• Caches are user-specific. In other words, if the same user performs the same search twice in a row, they may get a cached result. If a different user performs the same search, they will not get a cached result.
• Caching happens before any security services are applied, meaning that consent services or authorization services will be applied to results every time.

Caching FHIR Operations

Only the FHIR Operations listed in the Cacheable Operations setting are cached, and that list should contain only read-only operations. By default, this list contains $everything, $meta, $lookup, $validate-code and $translate. Each entry is an exact operation name, including the leading $ (for example, $everything). Entries are separated by commas. Setting a value replaces the default list. To cache no operations, set the value to NONE: any value that matches no operation name caches nothing. Any operation that is not listed, such as $export, $export-poll-status, $meta-add or $validate, is sent to the target server on every call.

A cached operation response is only reused for an invocation with exactly the same inputs: the same user, target server, operation name, resource type and ID, parameters (in any order), and request body.

Operations must be read-only because a cached operation response may be served up to the cache expiration (pagination_cache.expiration.seconds) out of date. For example, a $meta invocation that follows a $meta-add on the same resource can return the previous tags until the cached entry expires. Caching an operation that modifies data, or whose result changes as work progresses on the target server (for example, the status of an asynchronous job), causes clients to receive stale responses.

Buffering Search Results

In some cases, an enabled cache may also be used to buffer pages of search results.

As a simple example, suppose a client is performing a search against a FHIR Gateway using a route that matches 2 target servers. The client might specifically request pages of 10 results using a _count=10 parameter on the search URL. The FHIR Gateway will in turn ask each target server to provide search results satisfying this search.

If each target server returns 5 results, then all results will be returned immediately. However, if each server returns 10 results, then only the first target's results will actually be returned to the server. The remaining 10 results will be placed in the cache, and returned from cache when the client requests the next page of results. If the cache is disabled, then the FHIR Gateway will need to repeat the search a second time.

Detecting Cache Hits

When performing a FHIR Search or a FHIR Read operation, the client response from the gateway will include a header called X-Cache, which will contain a value starting with HIT if the operation results were fetched from the cache as opposed to being fetched from the target server.

In the case of searches which aggregate data from multiple targets, a request is considered a cache hit only if all target responses were served from the cache.