FHIR® REST API

Contents

  1. 1 Quick Start
  2. 2 Welcome
  3. 3 FHIR® overview
  4. 4 How to read this Implementation Guide
  5. 5 OAuth 2.0
  6. 6 Breaking changes
  7. 7 Integration patterns
  8. 8 Subpages 

Quick Start

Welcome

Welcome to the PKB FHIR® API!

This is the home of our Implementation Guide, which explains everything you need to know in order to interact with the API.

PKB is committed to external interoperability by making all our data available via FHIR compliant REST APIs. 

To this end we are currently building out our FHIR API and migrating away from our current custom implementation.  Our new single page application based UI is already using the new FHIR API to communicate with our backend. We are implementing resources iteratively in response to prioritised requirements. New resources (and new elements within already supported resources) will be added as needed. Resources in production can be seen here. Resources under development are listed here.

If you would like us to support something not yet documented, or if you have any other questions, please get in touch via help@patientsknowbest.com.

FHIR® overview

Fast Healthcare Interoperability Resources (FHIR, pronounced "fire") is an open standard which governments are increasingly adopting. FHIR describes data formats and elements (known as "resources") and an application programming interface (API) for exchanging electronic health records. NHS England is rapidly including this in its contracting. Developers find the standard easy to learn, and learning a standard is easier than learning different companies' proprietary APIs.

In October 2017, we began providing open FHIR API versions of all our existing proprietary REST API work. All our FHIR APIs will be for reading and writing, and PKB's front-end user interface will use these FHIR APIs to communicate with PKB's back-end database.

See https://www.hl7.org/fhir/STU3/ for the FHIR specification (Release 3).

How to read this Implementation Guide

This Implementation Guide is divided into several sections. You can navigate through these sections using the subpage navigation.

A popular section is PKB's FHIR Resource mappings, which explain which Resource types we support, and how our own Data Model maps into the FHIR data model.

Each FHIR Resource supported by PKB has its own dedicated section underneath the Resources page.

For each FHIR Resource, the documentation will provide the following:
  • An overview of what PKB uses that resource for.
  • A list of the relevant PKB entities.
  • The endpoints we support for that resource. This will detail supported interactions and search parameters (including which are mandatory) along with a list of PKB user types that are permitted to access the endpoint.
  • Mappings from the PKB Data Model into the FHIR resource.

OAuth 2.0

The majority of FHIR resources supported by PKB require the user to authenticate by providing an OAuth 2.0 bearer token.

Please see our OAuth 2.0 documentation for more information on how to use our authentication workflow to obtain a token.

Breaking changes

Clients of the FHIR API should be aware that PKB will continually and incrementally improve the API over time. There are many changes which we might make that we do not consider to be breaking changes.

Changes we reserve the right to make include (but are not limited to):
  • Changes to the structure or length of Access Tokens, Refresh Tokens, and Authorisation Codes. Clients should treat these as opaque, and be capable of storing any value up to a length of 4096 characters.
  • Adding new fields to an existing resource. We might initially offer a minimal set of data for a given resource, and expand the supported attributes over time. If your client reads the contents of a resource, you should build it such that it will not break if additional data is returned in the future.
  • Switching between contained and non-contained resources. Where a resource contains a reference to another resource, your client is expected to follow the resource reference regardless of whether the resource is internal ("contained"), external, or included (e.g. in response to an _include request). PKB anticipates these changing over time and your client should be able to handle this.
  • Changing OperationOutcome diagnostics text. PKB reserves the right to change the text returned in the diagnostics attribute of an OperationOutcome. We will use this attribute to return helpful information where available, but you should not code against it for flow control or error handling.
  • Changing code value display text. PKB reserves the right to change the display text associated with any code in our own code sets. We might improve the text over time to be more helpful, so you should not depend on it for flow control or error handling. Instead, you should use the code value itself. This includes our error codes returned in an OperationOutcome.
  • Default behaviour when no media type requested. The API behaviour outlined in this Implementation Guide is dependent upon the correct media type being requested, either using an Accept header or a _format parameter. Currently, we only support a media type of application/fhir+json. If no format is explicitly requested, PKB's behaviour is undefined, and may change in the future.
  • Default sort order when none specified. The order of resources returned from a search is undefined by default. No meaning should be given to the returned order unless the _sort parameter is a) supported for the interaction b) has been provided by the caller and c) been confirmed to have been applied for this specific interaction by inspecting the self link.

Integration patterns

The PKB FHIR API supports two different integration paradigms: REST and Messaging.

We already support the REST paradigm and are using this as a communication mechanism for our new SPA UI. Our plan is to add an asynchronous messaging paradigm to support external customers sending and receiving data. The table below outlines a few key differences along with some pointers for implementation considerations. 

  Low volume
 e.g. Mobile app		 Medium volume
 E.g. Trust feed		 High volume
 E.g. Region-wide feed

REST paradigm

(Datatype-centric)

  • Development typically iterates on Resources. Design should focus on:
    • Resource
    • Elements
    • Interactions

Examples

  • I want to build an app to read/write Appointments in PKB
  • create, read, update, delete, etc.
    • PKB will offer broad support for these interactions, delivering iteratively based on prioritisation

Optionally & additionally:

  • Batch: group multiple, separable CRUD operations into one request
    • PKB does not yet support the batch interaction
  • Transaction: group multiple CRUD operations into one atomic request
    • PKB does not yet support the transaction interaction
Notes

Pros

  • Requires minimal spec work
  • Likely to be supported by PKB ahead of other options

Cons

  • Individual interactions not externally identifiable / replayable
  • Client responsible for determining which CRUD operations required to achieve end goal

Messaging paradigm

(Event-centric)

  • Development typically iterates on Messages. Design should focus on:
    • Trigger event
    • Message definition
    • Resources
    • Elements
    • Actions expected of server

Examples

  • I want to send my encounter feed to PKB

Pros

  • Individual Messages identifiable, potential for duplicate detection, etc.
  • Client freed of responsibility for determining CRUD operations

Cons

  • Limited standardisation to date, design work required with client
  • Depending on client requirements, potentially extra development required

Pros

As for Synchronous Message, plus:

  • Higher throughput
  • Potential for multiple responses
  • Can easily operate synchronously if required

Cons

As for Synchronous Message, plus:

  • Requires customers to expose an endpoint
  • More complex error handling

Subpages