EU Health Data API
1.0.0-ballot - ballot 150

EU Health Data API, published by HL7 Europe. This guide is not an authorized publication; it is the continuous build for version 1.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/euridice-org/eu-health-data-api/ and changes regularly. See the Directory of published versions

Capability Discovery

Overview

Systems discover capabilities via FHIR CapabilityStatement (GET /metadata). Consumers inspect a provider's functionality before attempting transactions.

Transaction

Capability discovery uses the standard FHIR capabilities interaction:

GET [base]/metadata

The server returns a CapabilityStatement resource that declares:

  • Supported FHIR version
  • Supported resource types and profiles
  • Supported interactions (read, search, create, etc.)
  • Supported search parameters
  • Actor conformance and priority category support (see below)

Authorization Discovery

FHIR capability discovery at [base]/metadata declares the API interactions and security service coding. It is not OAuth endpoint metadata. Where SMART is selected by Authorization, the client discovers the authorization configuration from [base]/.well-known/smart-configuration, which publishes absolute endpoints, supported grants, capabilities, client-authentication methods, signing algorithms, and scopes. Interactive SMART modes additionally publish the authorization endpoint, PKCE and launch capabilities; Backend Services publishes client_credentials, asymmetric authentication, and applicable system/ scopes.

The discovered Authorization Server need not be co-located with the FHIR server. Its Authentication Service may be grouped with it or separately deployed; this does not create an additional SMART discovery endpoint or FHIR security-service code. See authentication and API authorization.

Where IUA is selected, the established deployment preconfigures the Authorization Server and the client applies the selected IUA metadata and transaction requirements. A CapabilityStatement does not replace either SMART or IUA metadata. See SMART conformance and IHE IUA ITI-103.

Provider Actors

Different provider actors advertise different capabilities:

  • Document Access Provider: Advertises document exchange capabilities (MHD ITI-67, ITI-68 transactions; ITI-105 with Document Submission Option)
  • Resource Access Provider: Advertises resource query capabilities (IPA patterns)

A system may implement one or both.

Actor Conformance via instantiates

Servers declare actor conformance using CapabilityStatement.instantiates, referencing the normative CapabilityStatements in this IG:

Consumers inspect instantiates to determine which actor roles and exchange patterns a server supports.

Priority Category Support

The EHDS ANNEX II priority categories are:

  • European Patient Summary (EPS)
  • Medication Prescription & Dispense (MPD)
  • Laboratory Results
  • Hospital Discharge Reports (HDR)
  • Imaging Reports
  • Imaging Manifests

Servers declare which priority categories they support by listing content IG canonical URLs in CapabilityStatement.implementationGuide. Consumers inspect implementationGuide to discover supported categories, then query by DocumentReference.type (LOINC) for specific document types. See Document Exchange for the type codes per priority category.

Profile Declarations

The normative CapabilityStatements in this IG declare supportedProfile for Patient using the EU Core Patient profile.

ITI-67 search results use base FHIR DocumentReference resources. This guide defines no DocumentReference return profile, so those CapabilityStatements declare none through supportedProfile.

Example Capability Discovery Flow

sequenceDiagram
    participant Consumer
    participant Provider

    Consumer ->> Provider: GET [base]/metadata
    Provider -->> Consumer: CapabilityStatement

    Note over Consumer: Consumer inspects:<br/>- instantiates (actor conformance)<br/>- implementationGuide (content IGs)<br/>- rest.resource.supportedProfile (profiles)<br/>- rest.resource (supported resources)

Capability discovery flow

Example: Server Supporting Multiple Priority Categories

See the example CapabilityStatement for a Document Access Provider serving Patient Summaries and Laboratory Reports.

The key elements a consumer looks for:

{
  "instantiates": [
    "...CapabilityStatement/document-access-provider-eu-api"
  ],
  "implementationGuide": [
    "http://hl7.eu/fhir/eps",
    "http://hl7.eu/fhir/laboratory"
  ],
  "rest": [{
    "resource": [{
      "type": "DocumentReference"
    }, {
      "type": "Patient",
      "supportedProfile": [
        "...patient-eu-core"
      ]
    }]
  }]
}

See Also