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 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 Search 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.

Note: Querying for a CapabilityStatement is a pre-requisite step for implementers that will provide information to the requester on what the responder supports.

Guidance is provided below anticipating that early adopters will likely start with more fundamental patterns of storing/retrieving FHIR Documents before expanding their capabilities to support the exchange of documents in various formats. One known evolution in this regard, is the departure from supporting only FHIR-assembled documents to supporting a hybrid model that supports FHIR Documents alongside documents in legacy formats (e.g., Binary). This evolution requires a different pattern to be applied. These patterns are differentiated below using an enumerated convention (e.g., 3A, 3B).

Document Retrieve Patterns: Fundamental

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

The simplest 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.

Document Retrieve Patterns: Intermediate

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. Implementer 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. 

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 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