Dealing with binary content

Some FHIR resources like DocumentReference or Media may contain binary “Attachments” as part of the resource.

Storing files as part of a resource

Please note that as a general limitation to the platform each resource may only contain one attachment. There are multiple possibilities how you can store files into FHIR resources:

Way 1: Base64 encoded

Use fields “contentType”, “data” and “title” from Attachment.

• Use the files mime-type as “contentType” field.
• Use the files filename (including file extension) as “title” field.
• Directly include the files data base64 encoded as “data” field.

Pros and Cons:

• Pro: Only one HTTPS request required
• Con: Works only with small amount of data

Way 2: Using “Binary” endpoint

The file and the FHIR resource may be transfered to the server separately.

Step 1: Send the file to the server:

POST /fhir/Binary

Send the plain binary data as request body. Send request header “Content-Type” with the mimetype of the files content. Send request header “Authorization” with your session token (same as for all other requests)

As response you will receive an http status 201 Created and a “Location” header containing an URL. The URL will have protokoll “midata-file://”.

Example upload using the command line tool “curl”:

curl -X POST -i -H "Content-Type:  application/pdf" -H "Authorization: Bearer 1234567890" https://test.midata.coop/fhir/Binary -T Filename.pdf

Step 2: Send the FHIR resource

Use fields “contentType”, “url”, “title” from Attachment.

• Use the files mime type as “contentType” field.
• Use the files filename (including file extension) as “title” field.
• Use the URL from the Location header from previous request as “url” field

Example:

...
attachment : {
    "contentType": "application/pdf",
    "url": "midata-file://5c5d604aaed6451868e4633b-AQAAAEs3Cw29fPdRY.....Gf1kno=-1747833",
    "title": "report.pdf"
}

The binary data from step 1 will be linked to the resource. The binary data will inherit all access permissions from the resource where it is used. Prior to linking the file to a resource the file data is not accessible on the server in any way. You can use the URL from the Location header exactly one time inside a resource. After use the URL becomes invalid. If the URL is not used as part of a resource for 24h after upload the data is deleted from the server.

Pros and Cons:

• Pro: Works for large files
• Con: Multiple requests required for data upload

Way 3: Use an external URL

If the file is available for download in the internet the MIDATA platform can download it.

Use fields “contentType”, “url” and “title” from Attachment

• Use the files mime type as “contentType” field.
• Use the files filename (including file extension) as “title” field.
• Use URL pointing to public file hosted on a different server as “url” field

The platform will download the file from the external server and include it into the resource.

Pros and Cons:

• Pro: Works for large files
• Con: File must be available on a public server

Retrieving file data from the platform

When you read any resource that contains an Attachment it will always have the fields “contentType”, “title”, “size” and “url” populated. This is not depended on the way the data was uploaded. The binary data itself is never included as part of the resource.

The url will always be an https URL pointing to the MIDATA instance.

Example:

{
    "resourceType": "DocumentReference",
    "id": "57fbb57c79c7212879740390",
    "status": "current",
    "type": {
        "coding": [
            {
              "system": "http://loinc.org",
              "code": "11488-4",
              "display": "Consult Note"
            }
        ]
    },
    ...
    "content": [
        {
            "attachment": {
                "contentType": "application/pdf",
                "url": "https://test.midata.coop/v1/records/file?_id=57fbb57c79c7212879740390",
                "size": 12034,
                "title": "report.pdf"
            }
        }
    ]
}

After obtaining the URL you can download the raw file from the given URL. You have two possibilities for providing the authorization token:

As header

Include the authorization token as request header as usual.

As url parameter

Include the authorization token as url parameter with name “access_token”. This method allows to download images into an HTML page using the “img” tag.