Reading Binary Data

FHIR Bundles returned by endpoints such as Get Pregnancy may include DocumentReference resources which indicate the presence of documents related to the subject of the bundle. The DocumentReference resource contains metadata about each document and includes one or more Attachment items which contain the details of the Binary resources for the document.

For example, the following FHIR model represents a DocumentReference for an Antenatal Summary Report as a PDF file:

JSON

{
    "resourceType": "DocumentReference",
    "id": "805c2896ea8ab8338fda825dddb6bffb2e95830a0950406c64660065ea8f59a7",
    "meta": {
        "versionId": "1",
        "lastUpdated": "2024-04-01T15:10:55.918+00:00"
    },
    "status": "current",
    "subject": {
        "reference": "Patient/8hE2mRmCrKzcRFN-6GPi4i8aYOcpyBykzD4OcK27huRWBmuwP0tXI-A9EW-jNSur"
    },
    "custodian": {
        "identifier": {
            "value": "ABC"
        },
        "display": "Acme Birth Centre"
    },
    "description": "Antenatal Booking Summary - PATIENT COPY",
    "content": [
        {
            "attachment": {
                "contentType": "application/pdf",
                "url": "Binary/33e2bef82f16f4c41ef3375740e34df4d3d877809fc3ea28631c520a09adb73c",
                "size": 35368,
                "title": "Antenatal Booking Summary - PATIENT COPY",
                "creation": "2024-04-01T15:10:50+01:00"
            }
        }
    ]
}

The content.attachment.url property contains a URL (relative to the Spine root URL) which may be used to download the binary content of the file as described below.

Binary files may be downloaded from the Spine in two formats: Native Binary or Base64 Encoded FHIR. The most efficient way to download the file is in the native binary format, however, Base64 serialisation within a FHIR Binary resource is also supported for clients which require this. The client may choose between these formats using the Accept header when making API requests to the Binary endpoint.

Reading the file in a native binary format

Accept: application/pdf

GET [baseUrl]/Binary/{binary-id}

To request the file in its native binary format, set an Accept header using the content type from the Attachment.contentType property, in the example above this is: application/pdf. Only the matching content type of the file may be specified, any other value (other than FHIR JSON types as described below) will return a 406 - Not Acceptable response code.

Reading the file as embedded Base64

Accept: application/fhir+json

GET [baseUrl]/Binary/{binary-id}

To request the file encoded in Base64 embedded within a FHIR Binary resource, set an Accept header on the request as application/fhir+json. For compatibility purposes, application/json is also allowed.

Note that this content type will use around 33% more bandwidth to transfer the same file since the binary is encoded using Base64.

The following example shows the response when using the embedded Base64 format:

JSON

{
    "resourceType": "Binary",
    "id": "33e2bef82f16f4c41ef3375740e34df4d3d877809fc3ea28631c520a09adb73c",
    "meta": {
        "versionId": "1",
        "lastUpdated": "2024-04-01T15:10:55.918+00:00"
    },
    "contentType": "application/pdf",
    "securityContext": {
        "reference": "Patient/8hE2mRmCrKzcRFN-6GPi4i8aYOcpyBykzD4OcK27huRWBmuwP0tXI-A9EW-jNSur"
    },
    "data": "JVBERi0xLjQKJdjGyc7J1c2u0MTGureusa6yrrEKMSAwIG9iag....." // Truncated
}