Breast Screening NZ FHIR Implementation Guide
1.1.0 - Release

Breast Screening NZ FHIR Implementation Guide - Local Development build (v1.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Developer Guide

HTTP Header Details

  • This is a list of any additions to standard HTTP header protocol

Request Headers

HTTP Header (Key) HTTP Header (Value) Description Mandatory / Recommended / Optional
Authorization Bearer {string} The OAuth2 access token Mandatory
X-Correlation-Id {string} Client provided
All requests should contain a unique transaction id in the X-Correlation-Id field
If present in the request this will be returned in the response, and can be used to track API calls
Preferred less than 64 characters
Recommended
Content-Type Application/json Supported content type Mandatory
request-context base64 Audit information Mandatory

Security

OAUTH2

This FHIR API uses standard OAUTH bearer token authentication.

All requests to this FHIR API must include an access token in the Authorization header.

​Authorized clients can obtain access tokens from the Health New Zealand authorization server (KeyCloak) using OAUTH2 Client Credentials flow to request the necessary OAUTH SMART scopes.

Scopes

See API for a description of the scopes required for each operation.

Request context

All FHIR API requests must include metadata about the context of usage for the application consuming the API. This is done by setting properties in the Request-Context custom header (which is a string containing a Base64-encoded JSON object).

property Required? Attribute value
userIdentifier YES The userid of the user as authenticated by RFCCS or other authorized PMS/health application.
purposeOfUse YES Set to "POPHEALTH"
userFullName YES Display name of the user of RFCCS or the PMS/health application.
hpiOrganisation YES The HPI Organisation identifier (format GAAANNN-A) for Secondary Prevention Service the application user is working within
hpiPractitioner optional If available, the HPI Practitioner identifier (Common Person Number) of the user
hpiFacility optional If available, the HPI Facility identifier of the health facility where the application is being used

The schema for defining and validating these properties can be found here

An example request context follows illustrating FHIR API access on behalf of the Northland / Te Tai Tokerau RF Secondary Prevention Service:

{
  "userIdentifier": "11AAbb@#",
  "purposeOfUse": "POPHLTH",
  "userFullName": "Alice Archer",
  "hpiOrganisation": {
    "type": "Organization",
    "identifier": {
      "use": "official",
      "system": "https://standards.digital.health.nz/ns/hpi-organisation-id",
      "value": "G0M086-B"
    }
  }
}

A schema for the Request-Context is available here