DocumentRetrieveRequest
API Information
The DocumentRetrieveRequest is a GET message that will use the following web service API endpoint information to retrieve a document through Surescripts.
| Operation | API Endpoint Description | Description |
|---|---|---|
| Document Retrieve | GET [base]/Binary?documentID= |
Returns the document in binary form. |
Note: As a responder you will be responsible for defining the endpoint information and URL for others to retrieve documents from your system. That information is returned in the DocumentSearchResponse from your system.
Content Types and Encodings
According to Section 3.1.0.1.9 of the FHIR® specification Content Types and encodings,
“The formal MIME-type for FHIR® resources is application/fhir+json or application/fhir+xml. The correct mime type SHALL be used by clients and servers.” Later in that same section, “UTF-8 encoding SHALL be used for the mime type application/fhir. This MAY be specified as a MIME type parameter to the application/fhir mime type, but is not required” because FHIR® uses UTF-8 for all request and response bodies. Since the HTTP specification (section 3.7.1) defines a default character encoding of ISO-8859-1, requests and responses SHALL explicitly set the character encoding to UTF-8 using the charset parameter of the MIME-type in the Content-Type header. Requests MAY also specify this charset parameter in the Accept header and/or use the Accept-Charset header.”
Because of these requirements, requests/responses will need to include a Content-Type in the HTTP header. Below is an example:
- Content-Type: application/fhir+json; charset=utf-8
Note: charset=utf-8 is not required by Surescripts, but is supported if sent.
Accept Header content v. the_format Request Parameter
The FHIR R4 specifications state that documents should be returned based on how they were requested which could be either via Bundles with Base64 encoded contents within a bundle or as streamed content. The Accept request-header field within a document retrieve request can be used to specify the media types that are acceptable for each response.
- If "application/fhir+xml" or "application/fhir+json" is specified in a request header’s Accept field, the document will be returned via FHIR bundles.
- Documents (ex: CCDAs, PLQs, binary files) that are returned to document requesters via bundles within the FHIR responses need to be Base64 encoded
- If other, ex: "application/pdf" (or other binary types), the requested document will be streamed directly to the requester
Alternatively, the FHIR® RLE product also supports the use of the “_format” parameter as described in Section 3.1.0.1.11 of the FHIR® specification as a way for document requestors to specify their preference to receive requested documents in a format other than what is included in the HTTP header (for situations where a requesting application can control the contents of their requests, but not the HTTP header due to the use of 3rd party communication software or other limitations).
Request example with “_format” parameter:
https://rle.surescripts.net/fhir/R4/Binary?documentId=CCDA123&repositoryId=urn:
oid:44.5555.66=urn:oid:77.8888.99&
_format=application/fhir+json
Be sure to note that use of the “_format” parameter in the request overrides any media request types specified in a request’s message header Accept field.