Scope

This capability supports the ability to retrieve known documents using the document's resource id.

Use Cases

The following CA:FeX use cases leverage this capability:

CA:FeX Transactions

This capability describes the FHIR implementation of the CA:FeX Retrieve Data (CA:FeX-3) transaction found in the Sequence Diagram for UC:02: Query and Retrieve Document.

HTTP Operations

This capability can be leveraged using HTTP GET requests. Implementers are expected to familiarize themselves with how searches are executed using the FHIR RESTful API framework.

See CA:FeX Actors and Transactions for more information on the supported HTTP operations.

HTTP GET

In the simplest case, a retrieve is executed by performing a GET operation in the RESTful framework:

GET [base]/[resourcetype]/id

Considerations for Document Retrieve Patterns

This pattern is predicated on the requestor knowing the id of the resource they are attempting to retrieve. 

Depending on the maturity and scope of the repository, the endpoints supported may be isolated to [base]/Bundle but the repository could potentially support additional document formats which would be retrieved from different endpoints.

Guidance is provided below anticipating that some adopters will solely support the ability to retrieve FHIR Documents directly, while others may choose to augment their capabilities to support a hybridized model that supports FHIR Documents alongside documents in legacy formats (e.g., Binary). This augmentation represents a different pattern that could be applied, these patterns are differentiated below using an enumerated convention (e.g., 3A, 3B).

Document Retrieve Patterns

CA:FeX-3A (Retrieve Document From FHIR Assembled Documents Repository)

The most straightforward method to retrieve a FHIR Document is to perform a read interaction using HTTP GET  [base]/[type]/[resource id] against a[base]/Bundle endpoint.

Per the FHIR Standard on the HTTP read interaction:

  • This returns a single instance with the content specified for the resource type.
  • This URL may be accessed by a browser.
  • The possible values for the Logical Id ("id") itself are described in the id type.
  • The returned resource SHALL have an id element with a value that is the [id]. 

Considerations for Document Retrieve Using Bundle Endpoints

Anchoring retrievals around a Bundle endpoint in this retrieval pattern is recommended for implementers that want to retrieve the FHIR Document using the known id for the Bundle. This retrieval pattern is expected to be used by implementers re-retrieving a Bundle that was previously identified in a search/or prior retrieval.


CA:FeX-3B (Retrieve Document from Hybrid Documents Repository)

Implementers are encouraged to incorporate patterns that allow for more comprehensive support for both FHIR-assembled and FHIR-enabled documents. Implementers that extend their capabilities can subsequently expect to support retrieval of documents using additional FHIR endpoints. 

This pattern anchors retrieval around [base]/DocumentReference and/or[base]/Binary endpoints using the HTTP GET command. 

Anchoring retrievals around a DocumentReference endpoint in this retrieval pattern is recommended for implementers that know the document they are retrieving is an embedded attachment in DocumentReference. This pattern can also be used to retrieve a DocumentReference if it was created and persisted through the use of the $docRef operation (see CA:FeX 2B), however this is not its primary function. 

Anchoring retrievals around a Binary endpoint in this retrieval pattern is recommended for implementers that know the document that they are retrieving is a Binary resource. This retrieval pattern is expected to follow a CA:FeX Search Against Hybrid Documents Repository (CA:FeX-2B), if the docRef operation is used and the attachment.url identifies the document can be retrieved from a FHIR Binary endpoint.

This pattern is anticipated to be further fleshed out as use cases requiring this pattern arise.

Document Retrieve Patterns: Supported Retrieval Parameters

The following examples are used to retrieve documents based on a known resource ID.

GET [base]/Bundle/[id]

GET [base]/DocumentReference/[id]

GET [base]/Binary/[id]

Cutting Edge Capabilities

FHIR Operations

FHIR Operations are used (a) where the server needs to play an active role in formulating the content of the response, not merely return existing information, or (b) where the intended purpose is to cause side effects such as the modification of existing resources, or creation of new resources. 

This specification does not currently define any custom operations for the Retrieve for a Document Capability. Unlike Submit a Document and Search for a Document capabilities, there are no existing operations that this specification has identified that directly impact retrieval of a document resources using resource id. 


  • No labels