10.5.4 | Twiin-04 | Search Resource(s)

This section describes the transaction of the retrieval of the FHIR® resources.

In the communication pattern notified pull these resources are referenced in the input field of the Notification or Workflow Task.
These input fields contain valueString in the input slice: query-available-resources.

1. Scope

This transaction supports the request of resources by the Requesting GtK to the Resource Server.

2. Use Case Roles

Actor: Requesting GtK

Role: Sends a request for resources on behalf of a retrieving user.

In the communication pattern notified pull, this is the Receiving GtK.

Actor: Responding GtK

Role: Processes the request and responds with the requested resources.

Note: In the communication pattern notified pull, this is the Sending GtK.

3. Referenced Standards

HL7® FHIR® standard STU3 https://hl7.org/fhir/stu3

4. Messages

4.1. Request message

The requesting GtK wants to obtain the resources that were referenced in the Task. These resources are retrieved using a FHIR® search interaction, i.e. executing an HTTP GET request to the resource servers FHIR® endpoint. If there is a relative path, the input valueString must be appended to the FHIR® base-url.

GET [base]/<ResourceType>?parameter=value

Percent-encoding of query parameters

When constructing URLs that include query parameters (e.g., code=...), it is important to percent-encode any reserved characters that could cause syntactic ambiguity, in accordance with https://datatracker.ietf.org/doc/html/rfc3986.

Exception
The slash character (/) may appear unencoded in query parameter values, as it is explicitly allowed in the query component of a URI per RFC 3986 (see Appendix A), and is commonly accepted by web servers and FHIR implementations.

The requesting GtK may provide the HTTP Accept header. Valid values for this header are application/fhir+json or application/fhir+xml. If none is set, the resource server will use its default.

4.2. Response message

The responding GtK returns the resource(s) that are requested.

The payload of this message consists of a FHIR® Bundle resource that contains the requested resource(s). This message is returned to the Receiving GtK.

The media type of the HTTP body must be either application/fhir+json or application/fhir+xml, based on the Accept header or default response content type.

When an error occurs an OperationOutcome resource must be returned with more details on the reason.

The HTTP response must be accompanied with the correct HTTP status code, e.g.:

200 OK - The search was processed and a valid response was returned
400 Bad Request - The search could not be processed or failed basic FHIR® validation rules
401 Not Authorized - Authorization is required for the interaction that was attempted
404 Not Found - The resource type not supported

The requesting GtK processes the response according to application defined rules.