FHIR Get Structured Record API

Introduction

The get FHIR record API uses a secure authentication and authorisation service. This uses recommended standards for identity and access management, using OpenID Connect and OAuth 2.0 methods, and also includes an additional security layer, where DDS checks it’s internal User Management service to ensure that each user is authorised with the necessary role based access profiles to use each particular application. This allows for tokens and user access to be centrally managed and revoked within the DDS User Manager application.

Two API calls are used for GetStructuredRecord:

Authenticate
Authorise/GetRecord

Authenticate

https://devauthentication.discoverydataservice.net/authenticate/$gettoken

Passing this JSON POST body (no header required)

{
  "grantType": "password",
  "clientId": "information-manager",
  "userName": "XXXXXXXXXXX",
  "password": "XXXXXXXXXXXX"
}

userName and password supplied securely in a separate private messages. This returns an authorisation access_token in this JSON reply, or a 404 HTTP Not Found response if the user is not recognised.

{
    "access_token": "xxxxxxxx",
    "refresh_token": "xxxxxxxxx",
    "refresh_expires_in": 1800,
    "not-before-policy": 1548863201,
    "scope": "profile email",
    "token_type": "bearer",
    "session_state": "79b125f5-f062-4a4c-a5a6-b2fa4519e8ad",
    "expires_in": 60
}

Authorise/GetRecord

https://devfhir.discoverydataservice.net/patient/$getstructuredrecord

Passing this JSON POST body

{
  "meta": {
    "profile": [
      "https://fhir.hl7.org.uk/STU3/OperationDefinition/CareConnect-GetStructuredRecord-Operation-1"
    ]
  },
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "patientNHSNumber",
      "valueIdentifier": {
        "system": "https://fhir.hl7.org.uk/Id/nhs-number",
        "value": "5558526785"
      }
    },
    {
      "name": "patientDOB",
      "valueIdentifier": {
        "system": "https://fhir.hl7.org.uk/Id/dob",
        "value": "1970-01-01"
      }
    }
  ]
}

Note: The patientDOB param is optional.

And set the Authorisation header to the value of the access_token returned from the authentication call.

Note: Access tokens expire if they are not used within 60 seconds.

If call 2 (authorise/get record) fails to authorise the access token against the Discovery identity and access management service, then an Unauthorised return value will be sent with a 401 HTTP Status (Unauthorized).

Success will return the FHIR bundle for the patient specified in the query parameters.

Introduction

Authenticate

Authorise/GetRecord

Workflow