Overview

This is a read-only, R4 FHIR API which aggregates data from all input routes, both FHIR and non-FHIR. The aggregation will perform STU3->R4 mappings as required. Complex access control applies since this contains data from multiple sources.

The data types available from this endpoint will be iteratively expanded over time, starting with Appointments. Please see the roadmap section for details of when other data types will be supported.

Although a Customer can read all data they send to their own Customer FHIR endpoint, such data must always go through the Aggregated FHIR endpoint in order to be made available to other users. Once support for a data type has been added to the aggregator, other system components (e.g. the web interface, Custom REST API, Facade FHIR endpoint) will be upgraded to read from the Aggregated FHIR endpoint, so that these will return data added to a Customer FHIR endpoint, ensuring that these data are available to users who will not be querying the Aggregated FHIR endpoint directly.

This endpoint is sometimes refered to as the “downstream” FHIR endpoint.

What You Can Do With This Endpoint

• Read data from other sources, even if it was provided in non-FHIR format

What You Cannot Do With This Endpoint

• Write data

• Read resource types that have not been included in PKB's aggregation logic. Please see the Capabilities section for a list of which resource types have been included so far.

• Read resources that you do not have authorisation to see. For example, a resource from a different organisation tagged with a privacy label that has not been granted to the caller.

Capabilities

Please see the following page for the capabilities of the aggregated endpoint as well as which data is currently surfaced from each: Aggregated Endpoint CapabilitiesPreview

Endpoint Requirements

Please see the following page for details on supported endpoints and requirements of these: Aggregated Endpoint API RequirementsPreview

Authentication

Customer

OAuth 2.0 System Client Credentials

Callers should obtain an access token by using the OAuth 2.0 Client Credentials workflow.

Note: the token endpoint is different from the one used for the Facade and Messaging FHIR endpoints, and the tokens are not interoperable.

Partner

Pending

App

NHS Login

Pending - will support NHS Login “asserted login identity” flow

Patients without NHS Login

Pending

Non-patient users

Pending

Validation and Business Rules

When designing an end-to-end integration that involves fetching data from the Aggregated FHIR endpoint, consideration must be given to relevant business logic applied at each stage of the data pipeline: input, processing and output.

Input

• Customer endpoint rules. Customers have a lot of freedom in what can be sent to a Customer FHIR endpoint, but there are a few rules that must be adhered to (see linked documentation).

Note: data not sent to a Customer FHIR endpoint can still be returned from the Aggregated FHIR endpoint; rules for such non-FHIR data are outside the scope of this FHIR documentation.

Processing

Once the resource has been accepted to the Customer FHIR endpoint, the PKB aggregator will attempt to aggregate that resource into the Aggregated FHIR endpoint. There are several business rules that apply to that processing:

• Supported resource types. Remember to check the capabilities of the Aggregated FHIR endpoint to confirm that the aggregator supports the relevant resource type(s).

  • Searches over unsupported resource types will return an empty search result; you should not assume a “successful” response implies the corresponding resource type has been added to the aggregation logic

  • Additionally, Customers must not provide a reference from a supported resource type to an unsupported resource type, since this is not supported by our aggregation logic

• Business rules that define whether a resource will be included in the Aggregated FHIR endpoint. The rules are outlined below.

  • Resources which do not meet these rules will be silently excluded from the data in the Aggregated FHIR endpoint

• Relevant merge logic. The aggregator will attempt to merge some resources together. There are resource type-specific rules about if/how this is down, which are outlined below.

  • Please also take note of the implications of the merge logic for corrective workflows

Output

The PKB web interface expects particular information to be in particular places within the FHIR resource. These rules are discussed below.

Merge Logic

The PKB aggregator will attempt to identify resources from multiple sources that contain information about the same entity, and merge those into a single resource.

For example, a single patient might have Patient resources on multiple Customer FHIR endpoints, including multiple resources on a single Customer FHIR endpoint. These resources might not contain the same information. The aggregated Patient resource returned from the Aggregated FHIR endpoint will contain the result of attempting to merge the upstream Patient resources together.

The table below provides more information on the relevant business rules.

Resources types not listed are not merged during the aggregation process.

Note: remember that (as per Inclusion criteria for the Aggregated FHIR endpoint) the system must be populated for every identifier or coding provided in the element which is used to group the relevant resource type for merging. Also, at least one identifier must be provided for any resource that is merged based on identifier.

Corrective Workflows

Elements included in the identity criteria of a particular resource type must not be updated. Instead, the resource containing the incorrect information must be deleted and then a new resource with the correct information sent. In addition, the new resource should be PUT to the same ID as the previous resource, in order to avoid dead references from any other resources pointing back to the newly-corrected resource.

Business Rules Affecting The Display of Aggregated FHIR Resources

General Rules

See also: FHIR FAQs: How does source tracking work?

Resource Specific Rules

See also: FHIR FAQs: Which FHIR fields does PKB draw from to populate the various elements in the web interface?

Examples

Please see the Examples page for step-by-step examples of how to interact with this endpoint.