HTTP API Caching

The performance of HTTP API clients can be significantly improved by reusing previously fetched resources. Web caches reduce latency and network traffic and thus lessen the time needed to display a representation of a resource. By making use of HTTP caching, HTTP API client applications become more responsive.

Enable HTTP API Caching

By default, HTTP API caching is disabled. It is recommended that customers enable it using properties "ohi.httpapi.cache.control.enable" and "ohi.httpapi.cache.control.cachesetting.metadata". It is essential to understand what this means however, and how clients are possibly impacted by this.

Concepts

HTTP API is using standard HTTP caching as described in Hypertext Transfer Protocol (HTTP/1.1): Caching. When enabled, HTTP API will add a Cache-Control header in the response it sends. Which one is added, depends on the type of the request and the resource:

  1. Requests for OpenAPI (Swagger) metadata use cache setting "METADATA".

  2. Requests for PHI (Personal Health Information) use cache setting "PHI".

  3. Requests for configuration data (brands, access roles and the like) use cache setting "CONFIGURATION".

  4. Requests for reference data (persons) use cache setting "REFERENCE".

  5. All others are not cached.

The available cache settings are supplied as seed data in table OHI_RESOURCE_CACHE_SETTINGS. This table can be accessed using resource "resourcecachesettings".

Adapt Caching

It is not possible to change any of the settings seeded by Oracle Health Insurance. It is however possible to create new cache settings. How to do this depends on the type of the request:

  1. For metadata requests: create a new record on Oracle Health Insurance_RESOURCE_CACHE_SETTINGS with a unique code. Give property "ohi.httpapi.cache.control.cachesetting.metadata" the value of that code. Now this setting will be used for all metadata requests.

  2. For non-metadata requests: create a new record on OHI_RESOURCE_CACHE_SETTINGS with a unique code. Create a new record in OHI_RESO_SETTINGS_OVERRIDE using resource "resourcesettingsoverride". The override will now take precedence over the seeded settings.

Considerations

Using caching means that for a certain period of time a stale version of an object may be used. So using caching properly always requires to find a balance between performance (very long expiry times, so cache can serve most requests) and getting up-to-date data. That’s why operational data like claims is not cached.

Cache behavior is always a negotiation between client and server. For example: for a certain resource the max-age is set to 3600, so a client may be served with a version that is at most 1 hour old. If the client program does not want that, the program can send a Cache-Control: max-age=0 or no-cache to get an up-to-date version from the server and not using the cached version.