Skip to main content

Migrating to the FHIR R4 retrieve attachment endpoint

Learn how to update your software to use the new API endpoint for downloading file attachments.

Page contents

Overview

This page explains how to migrate your software from the FHIR STU3 Retrieve attachment (A006) endpoint to the new FHIR R4 Retrieve attachment (A042) endpoint.

Migration will be required to support the download of files greater than 5MB.

Who will be affected

All partners integrated with the Retrieve attachment (A006, FHIR STU3) endpoint.

What we are doing

The Retrieve attachment (A006, FHIR STU3) API endpoint will be deprecated in February 2025.

As part of our sunsetting policy, this endpoint will be retired in February 2026. After this point, the endpoint will no longer be available for use.

Partners should migrate their software to make use of the new download endpoint - Retrieve attachment (A042, FHIR R4).

The new endpoint will only be made available via the internet and the API management platform, as HSCN access is deprecated, see Migrating from HSCN/CIS1 to APIM/CIS2.

Why we are making the change

The e-RS is raising the maximum file size limit to accommodate new care settings and share high-resolution media. The maximum file size will increase from 5MB to 100MB, and may increase beyond this in the future.

To enable fast, efficient transfer of large files, a new download endpoint is being introduced. This endpoint will allow direct file transfer from the e-RS object store.

The new download endpoint is being released early to give partners the opportunity to integrate before the file size limit increases.

A new endpoint will be launched, in later releases, for direct upload of large attachments.

Retrieve attachment (A006, FHIR STU3) will only support a maximum file size of 5MB or 5,242,880 bytes.

Next steps

What you need to do
  • Review the guidance on attachment availability
  • Understand the use of a HTTP 307 Temporary Redirect
  • Make endpoint changes

1. Review the guidance on attachment availability

With the introduction of direct uploads and downloads, files will now be processed asynchronously. This processing includes validation checks, for example, file type, file size, and malware scanning.

The asynchronous nature of this processing means that an uploaded file will not always be available for download. Files will only be retrievable when processing has completed and no threat is detected.

The availability status of an attachment can be retrieved via any endpoint that provides attachment metadata in its response. The availability status must be checked before attempting to download.

Details of the statuses and the guidance for partners can be found in:

2. Understand the use of a HTTP 307 Temporary Redirect

The new download endpoint makes use of a HTTP 307 Temporary Redirect status code.

It redirects the caller to a temporary location from which the file contents can be downloaded directly.

Partners must ensure they:

  • follow this redirect to retrieve the file
  • do not cache the temporary location
  • generate a new redirection each time the file is downloaded

The temporary location will only be valid for 5 minutes.

3. Make endpoint changes

Partners must replace calls to Retrieve attachment (A006, FHIR STU3) with Retrieve attachment (A042, FHIR R4).

The worked example shows how you can retrieve an attachment using both old and new endpoints.

This guide aims to highlight the types of changes required, it does not represent an exhaustive list of differences.

Please ensure you review the documentation for each endpoint in detail.

Worked example

Using A006

1. Retrieve attachment metadata

The DocumentReference resource represents an attached file and will include file metadata.

The resource is returned in the success response for any endpoint that provides details of an attachment.

For example:

{
    "id": "DocumentReference-80000",
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-DocumentReference-1"
        ]
    },
    "resourceType": "DocumentReference",
    ...
    "description": "Document Description",
    "content": [
        {
            "attachment": {
                "id": "80000",
                "extension": [
                    ...
                    {
                        "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-AvailabilityStatus-1",
                        "valueCoding": {
                            "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AvailabilityStatus-1",
                            "code": "AVAILABLE"
                        }
                    }
                ],
                "contentType": "application/pdf",
                "url": "Binary/19eb7224-dff3-4730-a5cb-67eac811f1a5",
                "size": 6,
                "title": "The filenamé.pdf",
                "creation": "2021-06-11"
            }
        }
    ]
}

Note that this example includes the file:

  • location
  • size (in bytes)
  • availability status

2. Ensure the file is available for download

The Extension eRS-AvailabilityStatus-1 must be AVAILABLE.

See the earlier section for guidance.

Review the guidance around attachment availability.

3. Ensure the file size is suitable for retrieval

Use the DocumentReference.content.attachment.size to check the file is not larger than 5MB or 5,242,880 bytes.

4. Retrieve the attachment

GET /STU3/Binary/19eb7224-dff3-4730-a5cb-67eac811f1a5 

HTTP 200 (OK)

Response Headers

Content-Disposition: attachment; filename="The_filenam_.pdf"

Response Body

<File Contents>

The filename returned in the Content-Disposition is currently sanitised to only include alphanumeric characters (A-Z/0-9) and periods (.) Other characters are replaced by an underscore (_)

Using A042

1. Retrieve attachment metadata

The DocumentReference resource represents an attached file and will include file metadata.

The resource is returned in the success response for any endpoint that provides details of an attachment.

For example:

{
    "id": "DocumentReference-80000",
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-DocumentReference-1"
        ]
    },
    "resourceType": "DocumentReference",
    ...
    "description": "Document Description",
    "content": [
        {
            "attachment": {
                "id": "80000",
                "extension": [
                    ...
                    {
                        "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-eRS-AvailabilityStatus-1",
                        "valueCoding": {
                            "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-AvailabilityStatus-1",
                            "code": "AVAILABLE"
                        }
                    }
                ],
                "contentType": "application/pdf",
                "url": "Binary/19eb7224-dff3-4730-a5cb-67eac811f1a5",
                "size": 6,
                "title": "The filenamé.pdf",
                "creation": "2021-06-11"
            }
        }
    ]
}

Note that this example includes the file:

  • location
  • size (in bytes)
  • availability status

2. Ensure the file is available for download

The Extension eRS-AvailabilityStatus-1 must be AVAILABLE.

Review the guidance around attachment availability.

3. Retrieve the attachment

GET /R4/Binary/19eb7224-dff3-4730-a5cb-67eac811f1a5 

HTTP 307 Temporary Redirect

Request Headers

Location: <e-RS Object Store Location>

GET <e-RS Object Store Location> 

HTTP 200 (OK)

Response Headers

Content-Disposition: attachment; filename="=?UTF-8?Q?The_filenam=C3=A9.pdf?=";filename*=UTF-8''The%20filenam%C3%A9.pdf

Response Body

<File Contents>

The Content-Disposition header will provide the filename using UTF-8 character encoding.

See RFC6266, RFC5987 and RFC2047 for further details.

Last edited: 12 February 2025 9:32 am