Implement Direct Upload and Download of Binary Content at the Binary Endpoint

[schwzr]

As part of MII's data transfer projects, some binary resources will probably have to be created on the FHIR servers. Therefore, it would be advantageous if this could be done as simply as possible and without “wrapping” in Base64 and JSON / XML resources.

The FHIR specification defines the REST API for Binary resources.
It allows binary resources to be created and read by sending only the content to the FHIR server via the HTTP body, and to be read by sending a non-FHIR Accept header.

Specifically, the following should apply to the binary endpoint:

General

• The Binary resource is always represented in the native FHIR format when wrapped in a Bundle.

• The _format overrides the accept header and SHALL be interpreted as using the standard FHIR mime types, even if the more generic mime types are given as a value.

• due to the way the web infrastructure works, it is not possible to make blanket rules about the relationship between the "Accept" field in the HTTP request, and the return type, which is why there is no hard rule about this. However, the intent is that unless specifically requested, the FHIR XML/JSON representation is not returned.

Download

• Implement Direct Download of Binary Content at the Binary Endpoint #2108

• When a read request is made with a FHIR type in the Accept header (e.g. "application/fhir+xml" or "application/fhir+json") the binary resource is returned in the requested FHIR format. This applies even when the binary data itself has a FHIR mime type.

• When the read request has some other type in the Accept header, then the content should be returned with the content type stated in the resource in the Content-Type header. E.g. if the content type in the resource is "application/pdf", then the content should be returned as a PDF directly. The _summary parameter does not apply in this case.

• Note that when client requests a Binary resource using a generic mime type (application/xml, text/xml, or application/json), the server SHOULD return the content directly if the content-type format matches the requested mime type (e.g. if the Accept header is application/json, and the contentType is vnd.xacml+json). However, servers might not always be able to interpret mime types correctly, and clients SHOULD be prepared to receive either format.

Upload

• Implement Direct Upload of Binary Content at the Binary Endpoint #2126

• When binary data is written to the server (create/update - POST or PUT), the data is accepted as is and treated as the content of a Binary, including when the content type is "application/fhir+xml" or "application/fhir+json", except for the special case where the content is actually a Binary resource.