Caching and Paging FHIR endpoint parameters

FHIR endpoints requesting a potentially big bundle of results are enabled to support paging out of the box, providing different modes regarding eager or lazy fetching of result subsets.

Parameters

Parameter name	Type	Default value	Short description
`lazyLoadBundles`	Boolean	false	whether page request parameters are delegated to the consumer route
`cacheBundles`	Boolean	false	whether result pages are cached (only effective if `lazyLoadBundles` is true)

By default, the FHIR servlet is configured to return in pages containing 20 resources. The client may demand for smaller or larger pages by specifying the _count parameter, but the maximum page size is by default 100.

lazyLoadBundles

If lazyLoadBundles is false, the request must be treated as if no paging is in effect, i.e. your service implementation returns all matching results to the FHIR servlet. IPF can care about caching the results as well as the result size and delivers them back to the caller in the requested chunks. Repeating requests are served from this cache rather than being forwarded into the consumer route.

This behavior can get inefficient if the overall result set for your service implementation is usually much bigger compared to the requested result subset, particularly when the service has no upper result limit. In this case, lazyLoadBundles should be set to true, which causes IPF to delegate paging into the consumer route. Your Camel route is now responsible of handling the following two cases:

size request: IPF adds a message header called FhirRequestSizeOnly to the exchange, which indicates that the route must only return the overall result size as integer value in the body.
subset request: IPF adds two message headers called FhirFromIndex and FhirToIndex to the exchange, containing the lower and upper bound of the request result subset. The route is expected to return the corresponding list of results.

cacheBundles

By default, the results are not cached unless cacheBundles is set to true. In this case already returned results are cached and reused on repeating requests, if possible. This is particularly useful if lazyLoadBundles is true as well; otherwise clients browsing back and forth in the result set would cause a potentially expensive request to the service imlpementation although the result subset has been fetched before.

Example

In the example below, only two entries per page were requested. As the total result size is three, the response bundle contains a link to the next page. Note that the URL is specific to the underlying HAPI FHIR library and must be treated as atomic unit.

    <Bundle xmlns="http://hl7.org/fhir">
       <id value="baa11115-c300-4043-8214-e72c97fe2984"/>
       <meta>
          <lastUpdated value="2016-04-19T13:46:49.159+02:00"/>
       </meta>
       <type value="searchset"/>
       <total value="3"/>
       <link>
          <relation value="self"/>
          <url value="http://localhost:8999/Patient?family=Test&amp;_count=2"/>
       </link>
       <link>
          <relation value="next"/>
          <url value="http://localhost:8999?_getpages=4fa95271-bb38-416b-a844-b83345280fbd&amp;_getpagesoffset=2&amp;_count=2&amp;_bundletype=searchset"/>
       </link>
       <entry>
          <resource>
             <Patient xmlns="http://hl7.org/fhir">
                <id value="4711"/>
                 ...
             </Patient>
          </resource>
       </entry>
       <entry>
          <resource>
             <Patient xmlns="http://hl7.org/fhir">
                <id value="0815"/>
                ...
             </Patient>
          </resource>
       </entry>
    </Bundle>

After calling directly the next URL, the second page is returned, containing the remaining patient entry together with a link to the previous page:

    <Bundle xmlns="http://hl7.org/fhir">
       <id value="0de9dd8b-cb98-406e-a1f6-3bb6e2a5eaa5"/>
       <meta>
          <lastUpdated value="2016-04-19T14:10:17.109+02:00"/>
       </meta>
       <type value="searchset"/>
       <total value="3"/>
       <link>
          <relation value="self"/>
          <url value="http://localhost:8999?_getpages=e8d02c62-6a96-48cc-904b-9740a7eac51f&amp;_getpagesoffset=2&amp;_count=2&amp;_bundletype=searchset"/>
       </link>
       <link>
          <relation value="previous"/>
          <url value="http://localhost:8999?_getpages=e8d02c62-6a96-48cc-904b-9740a7eac51f&amp;_getpagesoffset=0&amp;_count=2&amp;_format=xml&amp;_bundletype=searchset"/>
       </link>
       <entry>
          <resource>
             <Patient xmlns="http://hl7.org/fhir">
                <id value="9999"/>
                ...
             </Patient>
          </resource>
       </entry>
    </Bundle>