ResMed Core Implementation Guide
0.37.0 - ci-build International flag

ResMed Core Implementation Guide - Local Development build (v0.37.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Optimizations

By its nature, a web of discrete resources accessed via a REST interface, such as FHIR and its REST API is more “chatty” than some other styles of interface. In most use cases this is not an issue, and implementers are discouraged from trying to optimize without proof of inadequate performance. Some methods of optimization may result in fragile solutions or may favor certain situations while disadvantaging others.

With that in mind, some methods to improve API performance are discussed below.

The FHIR search specification supports several methods to improve the relevance of query results, including compound searches (“or” and “and” clauses), paging, and _sort. Many other search parameters and modifiers are documented in the specification; the following are only some of the more “interesting” or overlooked ones.

In all cases, callers should check the Bundle.link element with relation of self to see how the server interpreted the query request. A server is permitted to ignore, without warning or error, any search parameter it doesn’t support.

_include and _revInclude Search Parameters

Some of the most powerful search capabilities are the _include and _revInclude parameters which allow the caller to request that certain referenced or referencing resources are also included in the results. For example,

GET [base]/Patient?name=Smith&_include=Patient:managingOrganization

would return all Patient resources, where the patient is named Smith, and the managing Organization resources referenced by those patients. The Organizations would be flagged as secondary resources in the search results. Heading the other way,

GET [base]/Organization?name=Providence&_revInclude=Patient:managingOrganization

returns all Organization resources, where the organization is named Providence, and any patients who have that Organization as a managingOrganization. Both _include and _revInclude may be include in a query, and may be repeated to request additional related resources.

Recursing and Hierarchies

The iterate modifier applies an _include or _revInclude parameter to previously included secondary results. For example,

GET [base]/Procedure?date=2023-02-22&_include=Procedure:performer&_include=iterate:PractitionerRole:practitioner

would return all Procedures performed on the indicated date, along with the referenced performer.actor resource (which could be one of half a dozen resource types), and, if that resource is a PractitionerRole, also return the practitioner it references. In some cases, such as Observation.hasMember (which is in turn a reference to an Observation), the iteration could repeat multiple times.

Alternatively, the above and below modifiers can be used on certain resources to traverse a hierarchy, such as an organization.

Chaining

Chaining (and reverse chaining) allow you to search based on criteria of a referenced (or referencing) resource. For example,

GET [base]/Observation?device:Device.serialNumber=1234

returns all Observations that have a device with serial number 1234. Since the chained resource isn’t included by default, you’d need to use &&_include=device to include the matching devices in the results. Alternatively,

GET [base]/Device?_has:Observation:device:code=ControlFETShortCircuit

returns all Devices that are referenced in an Observation device element, where the Observation.code is ControlFETShortCircuit.

_summary and _elements

Unlike most other search parameters, which control the resources returned, _summary and _elements modify the contents of the returned resources. _summary requests only “summary” elements be returned (those marked with a σ in the specification), or alternatively, only “text” or “data” elements, or just a count of resources. The _elements parameter requests that only listed elements be returned. Note that for both parameters, mandatory and modifier elements will always be returned.

The value of these parameters could be debated, since stripping content from a large number of resources may cause a delay in receiving results, while the reduced payload size may not be of significant benefit on a small search result.

Conditional Operations

The FHIR specification supports two kinds of conditional operations that may be used either with individual resources or with resources included in a transaction or batch Bundle.

Conditional Headers

The HTTP Headers If-Modified-Since, If-None-Match, and If-None-Exist may be used to control the results of a conditional create, conditional read, conditional update, or conditional delete.

Conditional References

A search that returns exactly one match may be specified as the target of a resource update or delete.

Within a batch or transaction Bundle, a resource may refer to another resource using a conditional reference, which is a search that returns exactly one match. This mechanism allows, for example, creation of an Observation referencing the Device with serialNumber 1234, without having to separately query for that device to obtain its id. This may reduce the number of queries needed prior to creating or updating a resource. When the resource is actually processed, the “conditional” search reference is replaced by an actual resource reference.

For example, on submission, a Bundle with a resource containing a reference of the this form:

{
  "resourceType" : "Bundle",
  "id" : "airsense-10-summary-bundle",
  "type" : "transaction",
  "entry" : [
    ...
    {
      "fullUrl" : "http://example.org/fhir/Observation/airsense-10-summary",
      "resource" : {
        "resourceType" : "Observation",
        "id" : "airsense-10-summary",
        ...
        "effectiveDateTime" : "2021-05-07",
        "issued" : "2021-05-07T13:28:17.239-05:00",
        "device" : {
          "reference": "Device?identifier=66793269986"
        },
        ...
      },
    ...
  }
}

is updated to this form:

{
  "resourceType" : "Bundle",
  "id" : "airsense-10-summary-bundle",
  "type" : "transaction",
  "entry" : [
    ...
    {
      "fullUrl" : "http://example.org/fhir/Observation/airsense-10-summary",
      "resource" : {
        "resourceType" : "Observation",
        "id" : "airsense-10-summary",
        ...
        "effectiveDateTime" : "2021-05-07",
        "issued" : "2021-05-07T13:28:17.239-05:00",
        "device" : {
          "reference" : "Device/airsense-10"
        },
        ...
      },
    ...
  }
}

Conditional references are not currently supported by CHP.