Publish and subscribe API

This is draft API and is not yet on production servers

The Publish/Subscribe pattern enables entities to subscribe to data changes, so that when changes are made to a patient’s record, the new data (or a selected subset, according to the subscription) will be pushed directly to subscriber.

PKB Implementation


PKB will send the entire update upon PKB data receipt. (Large documents will be in the form of links allowing separate download). Subscribers can specify the data they want to receive, e.g. just ids (if only notification required) or full data. Data will be formatted as FHIR resources. PKB will be rolling out pub-sub data points on a published timeline.

Connectivity and Transmission

Clients will whitelist the PKB IP as needed for an outgoing connection -- PKB will not open any connection to the client.  Clients will connect to PKB on port 443, starting with an HTTPS-based handshake, upgrading into an encrypted WebSocket connection, which enables full two-way messaging over TCP.  This allows clients to simply stay connected, simplifying security, as they are already authorized. The OAuth2-based authentication paradigm in place for the REST API will be utilized. Clients will call PKB and authenticate via REST protocols as opposed to PKB sending confidential data to a URL. This is a more secure option which fits into PKB’s current authentication model.

Transmission will occur real-time; as data arrives at PKB from disparate sources, PKB will publish it to the appropriate connected subscribers.


PKB will host a webform where subscribers can express their desire to receive updates. Technical contact details should be provided. Details to be finalized but this may be rolled into the current REST API enrolment form.


PKB will provide the ability for clients are able to set up filters to specify the data set of interest. The filtering will be managed by PKB, ensuring that the client receives the subset requested.

The client will specify this by submitting a JSON structured document describing data they wish to receive. Data can be filtered in the following ways:  

  • time based - time to start (if not specified => current time)

  • data type (FHIR Resource) - a list can be provided

  • data source - initially this would provide the option of excluding data sent from the subscriber, but this could be extended.


dataTypes: include[TestResult, SURVEY, Consent],

dataSourceType: exclude[<SendingOrgID>],

from:20160601T18:00:23Z [we would default to now if no value was presented]



PKB will publish updates on data points that correspond to PKB FHIR compliant data points. These roughly correspond to the following.




  • CONSENT - changes in team sharing as well and ‘additional consent’


  • FILE - metadata on uploaded files; binary content will be linked, not included









  • USER



Entitlements to receive patient data updates follow the PKB paradigm for consent. The subscribing team must have the decryption keys to the patient data - no data or update publications will be sent for a patient which has not consented a team to see their data. In addition to this no data will be published unless the team’s privacy sharing options (as set in the patient’s consent) match the privacy labeling of the data point.

For example, if information from a sexual health clinic is sent about a patient and automatically labeled Sexual Health, this update will only reach subscribers who have the patient’s consent to view their Sexual Health data.

Replay / Initial Connection

Replay allows subscribers to receive updates they may have missed due to connection unavailability, or when first connecting to a patient’s record. This is the same as the pub-sub request but specifying a start-date which will cause historic information to be pushed immediately, in the same format as the live data stream (FHIR resources).