Writing Binary Data

BadgerNet Spine clients can store file attachments within care records held within BadgerNet by using the Binary endpoint to upload binary data such as PDF files or images, and the DocumentReference FHIR resource to associate data with records.

Similarly to Reading Binary Data, there are two methods to upload files to the Spine: Native Binary or Base64 Encoded FHIR. The preferred method is to upload the file in its native binary format since this avoids the need to encode the file as Base64 which increases the size of the payload.

Uploading a file in native binary format

This is the preferred method to upload attachments to the FHIR Spine since there’s no additional overhead to encode the data.

Step 1: Upload the file contents

Content-Type: application/pdf

POST [baseUrl]/Binary

To upload the file, POST the file to the Binary endpoint, setting the Content-Type header with the MIME type of the file contained within the request. If successful, the API will respond with a 201 - Created status code, and include a Location header in the response with a temporary URL which should be used for Step 2.

Response:

201 - Created

Location: /UploadedFile/88861cbe35504b603276485e086e74ad3a5f7a96386f0ecce729d793a2637848

Step 2: Link the file to the record

To associate the uploaded file with a care record, send a DocumentReference resource to the Spine containing the temporary URL from Step 1 within the attachment.url property. Once the file has been associated with the record, the URL will no longer be usable. Multiple attachments may be associated with each DocumentReference if appropriate, for example, multiple related images which comprise a single document. The resource may be included in a request to any endpoint which supports writing, such as Updating a pregnancy.

The Content Type specified in the attachment.contentType property must match that of the uploaded file

JSON

{
    "resourceType": "DocumentReference",        
    "status": "current",    
    "description": "Optional description of the document",
    "content": [
        {
            "attachment": {
                "contentType": "application/pdf",
                "url": "/UploadedFile/88861cbe35504b603276485e086e74ad3a5f7a96386f0ecce729d793a2637848",                
                "title": "Title of the attachment"
            }
        }
    ]
}

Uploading a file as Base64 encoded FHIR

As an alternative to the two-step native binary upload described above, it is also possible to send file contents as Base64 encoded strings in a single API request.

While this approach requires fewer API calls, a significant disadvantage is the increase in payload size due to the encoding in Base64, which will increase the request size by around 33%. The capability is reserved for compatibility with legacy systems.

To upload a file using inline Base64, send a DocumentReference resource to the Spine containing the binary content as a Base64 encoded string within the attachment.data property:

JSON

{
    "resourceType": "DocumentReference",        
    "status": "current",    
    "description": "Optional description of the document",
    "content": [
        {
            "attachment": {
                "contentType": "application/pdf",
                "data": "JVBERi0xLjQKJdjGyc7J1c2u0MTGureusa6yrrEKMSAwIG9iag.....", // Truncated
                "title": "Title of the attachment"
            }
        }
    ]
}