MyHealth@Eu NCPeH API
10.0.0-ci - ci-build 150

MyHealth@Eu NCPeH API - Local Development build (v10.0.0-ci) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Resource Retrieval

This page describes the implementation options of the Search and Retrieve Resources task.

Business View

The overall business scenarios associated to this task are described in the Business view page.

Application View

The implementation-independent sequence diagrams associated to this task are described in the Application view page.

Implementation pre-requisites

The MyHealth@EU general architecture requires that no assumptions are made on the way the service is implemented at the national level.

This implies that any solution adopted for the NCPeH to NCPeH communications has to work properly independently from the fact that a HL7 FHIR server, or any other national solution, is locally adopted.

Implementation alternatives

This page documents the generic search and retrieval pattern applicable to any HL7 FHIR resource type that is not already covered by a dedicated page, such as Document Retrieval, Prescribed item Retrieval, or Dispensation Provision and Retract.

In this version, this pattern is limited to the Immunization resource. Additional resource types may be added to the scope of this pattern in a later version of this guide.

Two alternative interactions are available, depending on whether the identifier of the resource is already known:

  • Search resources: the Requesting NCP searches for resources of a given type matching a set of search parameters.
  • Get Resource: the Requesting NCP retrieves a specific resource instance using its logical id.

Responding NCPRequesting NCPResponding NCPRequesting NCPRequesting NCPResponding NCPResponding NCPResponding NCP1eHDSI Immunization Search Request2Request processed3eHDSI Transform, Translate4eHDSI Immunization Search Response

Figure 1 - Search Resources

eHDSI Immunization Search Request

The Requesting NCP initiates a search query for the Immunization resource type using the FHIR API call:

GET $server/Immunization?<searchParameters><modifiers>

The query includes search parameters and modifiers to refine the search criteria.

Search Parameters
Note: The conformance verbs, such as SHALL, used in the "Requesting NCP" and "Responding NCP" optionality columns indicate the actor's capability to support that parameter, not whether the parameter is actually used in a given search.
Parameter searchParameter type Requesting NCP Responding NCP notes
Status status token SHALL SHALL Immunization event status
Vaccination (non)-Administration Date date date SHOULD SHOULD
Patient business identifier patient reference SHALL SHALL The patient for the vaccination record
patient.identifier token SHALL SHALL Chained parameter
Vaccine Product Administered vaccine-code token SHOULD SHOULD
Target Disease target-disease token MAY MAY The target disease the dose is being administered against
eHDSI Immunization Search Response

The Responding NCP returns a FHIR Bundle containing the search results.

Bundle.where(type='searchset').entry.resource.ofType(Immunization)
Search HTTP Error Response Codes
HTTP Response Description
400 Bad Request search could not be processed or failed basic FHIR validation rules
401 Unauthorized authorization is required for the interaction that was attempted
404 Not Found resource type not supported, or not a FHIR end-point

Step-by-Step Breakdown: Resource Retrieval

Responding NCPRequesting NCPResponding NCPRequesting NCPRequesting NCPResponding NCPResponding NCPResponding NCP1eHDSI Get Immunization by Id Request2Request processed3eHDSI Transform, Translate4eHDSI Get Immunization by Id Response

Figure 2 - Get Resource

eHDSI Get Immunization by Id Request

The Requesting NCP retrieves the selected resource using a valid FHIR API URL in the form:

GET $server/Immunization/id

The Requesting NCP sends a request to the Responding NCP for the selected resource.

eHDSI Get Immunization by Id Response

The Responding NCP returns the selected resource.

Resource Retrieval HTTP Error Response Codes
HTTP Response Description
401 Unauthorized authorization is required for the interaction that was attempted
404 Not Found selected resource not found
410 Gone selected resource is no longer available
403 Forbidden / Request Type Not Supported HTTP request specified is otherwise not a legal value

Open points to be further assessed

The set of resource types, and the associated search parameters, that need to be supported by this generic pattern are still to be assessed.