Documents | Binary

0. References

There are situations where it is useful or required to handle pure binary content using the same framework as other resources. Typically, this is when the binary content is referred to from other FHIR Resources. Using the same framework means that the existing servers, security arrangements, code libraries etc. can handle additional related content. Typically, Binary resources are used for handling content such as:

• PDF Documents
• Images
• HL7 Structured Documents (e.g. CDA or FHIR Documents)

Binary resources behave slightly differently to all other resources on the RESTful API. Specifically, when a read request is made for the binary resource that doesn’t explicitly specify the FHIR content types “application/fhir+xml” or “application/fhir+json”, then the content should be returned using the content type stated in the resource. e.g. if the content type in the resource is “application/pdf”, then the content should be returned as a PDF directly.

The HL7 specification states that “the intent is that unless specifically requested, the FHIR XML/JSON representation is not returned”. This behaviour is implemented in the Reference Implementation and would be expected of any standard implementation.

1. Read

Return a single Binary for the specified id.

All requests SHALL contain a valid ‘Authorization’ header and SHALL contain an ‘Accept’ header. The `Accept` header indicates the format of the response the client is able to understand, this maybe be one of the following application/json+fhir or application/xml+fhir, this will return the requested resource as FHIR Binary resource.

The Binary will be returned in a native format (i.e. not contained within a FHIR resource) if no MIME type is not specified, an appropriate MIME type is included or a wild card (*/*) is included within the request header.

Common health related MIME types are listed below:

Although this page is describing a FHIR Binary endpoint, a Binary resource can be retrieved from any url. If a FHIR Binary endpoint is used then the resource SHALL be available as both a Binary resource and as a standard URL resource. The default behaviour is that of a URL resource

For Binary resources, the result of a query are different when compared to the rest of FHIR. There are specific ways to indicate the format of the response expected by the server. This is via the client specifying the format of the response either via a _format override on the query parameter of by using a “content-type” HTTP header in the request.

1.1. Query 1 - Default Query

MUST be supported.

Server returns the document using the native mime type of the document – No FHIR resources are returned.

1.2. Query 2 - Format Override 1

MUST be supported.

Server returns a FHIR Binary resource in the requested format with the “document” BASE64 encoded within the content element.

1.3. Query 3 - Format Override 2

SHOULD be supported.

Server returns a FHIR Binary resource in the requested format with the “document” BASE64 encoded within the content element

1.4. Query 4 - Format Override 3

SHOULD be supported.

Server returns a FHIR Binary resource in the as per format_1 as _format overrides the HTTP Accept headers. The “document” is BASE64 encoded within the content element

1.5. Response

A full set of response codes can be found here API Response Codes. FHIR Servers SHALL support the following response codes:

2. Search

The binary is not searchable as the other API resources are, however, please refer to DocumentReference for a mechanism to gain access to Binary information through a API.

3. Example

3.1 cURL

Return a Binary resource, the format of the response body will be xml. Replace ‘baseUrl’ with the actual base Url of the FHIR Server.

curl -X GET -H 'Accept: application/json+fhir' -H 'Authorisation: BEARER [token]' -v 'https://data.developer.nhs.uk/ccri/STU3/Binary/5b1e91f0ccf84d0001fffe6d'

3.2 Explore the Response

Explore the response in XML & JSON on the Reference Implementation below

Reference Implementation
Direct link Binary unstructured document download