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

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.

OAuth2

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

Please see our OAuth2 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.

Subpages