Implementation Guide
ePA Common
Version 1.0.5-ballot.1 - draft

Query API: Allgemeine Anforderungen Suche und Sortierung

Seiteninhalt:

Diese Seite beschreibt Standard-API-Zugriffe für eine clientseitige Suche und Bereitstellung von Daten des FHIR Data Service. Im Detail bedeutet dies das Navigieren in Suchergebnisseiten, die kompakte Suche mit verknüpften FHIR-Ressourcen als auch die Suche unter Nutzung von Vergleichsoperatoren.

Suche

Die FHIR-Schnittstellen des FHIR Data Service unterstützen standardmäßige FHIR-Suchoperationen gemäß den Vorgaben der FHIR-Spezifikation. Bei einer Suche wird ein Search Set Bundle zurückgegeben.

Der FHIR Data Service MUSS unbekannte Suchparameter ignorieren. Siehe http://hl7.org/fhir/R4/search.html#errors.

fullUrl in FHIR Bundles

Der FHIR Data Service MUSS sicherstellen, dass das fullUrl-Feld in jedem Entry (Bundle.entry.fullUrl) wie in der Standard HL7 FHIR Spezifikation als absolute URL oder als UUID-basierte URI (urn:uuid) angegeben wird. Relative Pfade sind im fullUrl-Feld nicht zulässig. Für absolute URLs gilt zusätzlich, dass sie das Format [base]/[Ressourcentyp]/[ResourceId] aufweisen müssen. Der Host der absoluten URL im Feld Bundle.entry.fullUrl MUSS dabei stets epa4all sein.

Beispiel:

http://epa4all/epa/audit/api/v1/fhir/AuditEvent/ea01ccbc-aa5d-4c34-8292-d95678d52c98

Eine UUID-basierte URI MUSS das Format urn:uuid:[UUID] haben, zum Beispiel

urn:uuid:ea01ccbc-aa5d-4c34-8292-d95678d52c98

Wenn im Bundle.entry.fullUrl eine UUID-basierte URI (urn:uuid) verwendet wird, MÜSSEN alle Referenzen innerhalb desselben Bundles auf diese Ressource ebenfalls in der Form urn:uuid:[UUID] angegeben werden. Es DARF NICHT eine Mischung von absoluten URLs und UUID-basierten URIs und relativen Referenzen innerhalb eines Bundles verwendet werden.

Der FHIR Data Service MUSS sicherstellen, dass relative Referenzen wie "literal" Referenzen in der Form [Resourcetyp]/[ResourceId] NICHT im Feld Bundle.entry.fullUrl verwendet werden. Alle Verweise auf Ressourcen innerhalb des Aktensystems MÜSSEN entweder als absolute URLs oder als UUID-basierte URIs (urn:uuid) angegeben werden.

Beispiele Standard-Suchparameter:

_id: Bezieht sich auf die logische ID der Ressource

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_id=ea01ccbc-aa5d-4c34-8292-d95678d52c98

_lastUpdated: Kann verwendet werden, um Ressourcen basierend auf dem letzten Änderungszeitpunkt auszuwählen

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_lastUpdated=2025-15-01

Einbeziehung verknüpfter Ressourcen in das Ergebnis

_include:

In FHIR wird der Suchparameter _include verwendet, um zu fordern, dass der Server nicht nur die angeforderten Ressourcen, sondern auch andere Ressourcen, die über eine angegebene Referenz mit ihnen verbunden sind, zurückgibt. Dieser Parameter ist besonders nützlich, um verknüpfte Ressourcen in einer einzigen Abfrage abzurufen, wodurch die Notwendigkeit nachfolgender Anfragen verringert wird. Beispielsweise, wenn eine Abfrage an MedicationRequest-Instanzen mit einem _include-Parameter wie MedicationRequest:medication durchgeführt wird, gibt der Medication Service die angeforderten MedicationRequest-Instanzen zusammen mit verknüpften Medication-Instanzen zurück. Das bedeutet, dass eine Liste von Medication-Instanzen ebenso erhalten ist.

Beispiel

GET [base]/epa/medication/api/v1/fhir/MedicationRequest?_include=MedicationRequest:medication

In dieser Abfrage bedeutet:

  1. MedicationRequest der FHIR-Ressourcentyp, der abgefragt wird

  2. _include=MedicationRequest:medication die Anweisung an den Medication Service, die Medication-Instanzen einzubeziehen, auf die in den MedicationRequest-Instanzen referenziert wird

Diese Abfrage gibt ein Search Set Bundle zurück, welches alle im Medication Service verfügbaren MedicationRequest-Instanzen enthält - also auch zugehörige Medication-Instanzen. Hinweis: Dies kann potenziell eine große Ergebnismenge bedeuten und ist davon abhängig, wie viele MedicationRequest-Datensätze gespeichert sind.

Der FHIR Data Service MUSS die _include-Suche gemäß der FHIR R4-Spezifikation unterstützen, sodass referenzierte Ressourcen innerhalb der Suchergebnisse automatisch mit einbezogen werden können.
_revinclude:

In FHIR ist _revinclude ein Suchparameter, der es ermöglicht, Ressourceninstanzen in die Ergebnismenge einzubeziehen, die jeweils auf die primäre Ressourceninstanz referenziert.

Der FHIR Data Servic MUSS die _revinclude-Suche gemäß der FHIR R4-Spezifikation unterstützen, sodass Ressourcen, die auf die gesuchten Ressourcen verweisen, innerhalb der Suchergebnisse automatisch mit einbezogen werden können.

Beispiel

GET [base]/epa/medication/api/v1/fhir/MedicationRequest?_revinclude=MedicationDispense:prescription

In dieser Abfrage bedeutet:

  1. MedicationRequest der FHIR-Ressourcentyp, der abgefragt wird

  2. _revinclude=MedicationDispense:prescription die Anweisung an den Medication Service, die MedicationDispense-Instanzen einzuschließen, die eine authorizingPrescription-Referenz haben, welche wiederum auf die MedicationRequest-Instanzen verweist

Diese Abfrage gibt ein Search Set Bundle zurück, welche MedicationRequest-Instanzen zusammen mit den MedicationDispense-Instanzen enthält.

Vergleiche und Präzision für Zahlen, Daten und Mengen

Bei einer Suche, die numerische oder Datumsparameter umfasst, hängen die verwendeten Werte von der Präzision des bereitgestellten Parameters ab. Zum Beispiel erstreckt sich für das Datum 2025-02-11 der Bereich von 2025-02-11, um 00:00:00 Uhr (inklusive) bis 2025-02-12, um 00:00:00 Uhr (exklusive).

Präfix

In FHIR werden Gleitkommazahlen durch Datentypen wie decimal und quantity dargestellt, die die Präzision des gespeicherten Werts erfassen. Dies schließt jedoch einige Felder aus, die einfache Ganzzahlen verwenden. Suchoperationen in diesen Feldern führen zu exakten numerischen Übereinstimmungen. Bei numerischen Vergleichen (number, quantity) mit einem einzelnen Wert sind nachfolgende spezifische Präfixe anwendbar. Wenn kein Präfix angegeben wird, wird standardmäßig eq verwendet. Weitere Details finden sich hier: FHIR R4 Search Prefix

Präfix Beschreibung
eq Der Wert des Parameters in der Ressource ist gleich dem bereitgestellten Wert.
ne Der Wert des Parameters in der Ressource ist nicht gleich dem bereitgestellten Wert.
gt Der Wert des Parameters in der Ressource ist größer als der bereitgestellte Wert.
lt Der Wert des Parameters in der Ressource ist kleiner als der bereitgestellte Wert.
ge Der Wert des Parameters in der Ressource ist größer oder gleich dem bereitgestellten Wert.
le Der Wert des Parameters in der Ressource ist kleiner oder gleich dem bereitgestellten Wert.

Datumsangaben haben einen Bereich, der auf ihrer Präzision (Jahr, Monat, Tag) basiert. Für Typen wie Range oder Period sind eindeutige obere und untere Grenzen definiert. Es gibt spezifische Präfixe für derartige Vergleiche. Wird kein Präfix angegeben, ist eq die Standardwahl.

Präfix Beschreibung
eq Der Bereich des Suchwerts enthält den Bereich des Zielwerts vollständig.
ne Der Bereich des Suchwerts enthält den Bereich des Zielwerts nicht vollständig.
gt Der Bereich oberhalb des Suchwerts überlappt mit dem Bereich des Zielwerts.
lt Der Bereich unterhalb des Suchwerts überlappt mit dem Bereich des Zielwerts.
ge Der Bereich oberhalb des Suchwerts überlappt mit oder schließt den Bereich des Zielwerts vollständig ein.
le Der Bereich unterhalb des Suchwerts überlappt mit oder schließt den Bereich des Zielwerts vollständig ein.
sa Der Bereich des Parameterwerts beginnt nach dem Zielbereich.
eb Der Bereich des Parameterwerts endet vor dem Zielbereich.
Der FHIR Data Service MUSS numerische und Datums-Suchparameter so verarbeiten, dass die Suchwerte entsprechend ihrer Präzision interpretiert werden. Beispielsweise MUSS eine Suche nach 2025-02-11 den Bereich von 2025-02-11T00:00:00 (inklusive) bis 2025-02-12T00:00:00 (exklusive) abdecken. Der FHIR Data Service MUSS die in der FHIR R4-Spezifikation definierten Vergleichspräfixe für numerische (number, quantity) und Datumsparameter (date, Range, Period) unterstützen. Falls kein Vergleichspräfix angegeben wird, MUSS der FHIR Data Service standardmäßig das Präfix eq verwenden. Der FHIR Data Service MUSS die folgenden Vergleichspräfixe für numerische Werte (number, quantity) unterstützen: eq, ne, gt, lt, ge, le Der FHIR Data Service MUSS die folgenden Vergleichspräfixe für Datumswerte (date, Range, Period) unterstützen: eq, ne, gt, lt, ge, le, sa, eb Der FHIR Data Service MUSS sicherstellen, dass Suchoperationen für Felder mit Ganzzahlen (integer) nur exakte numerische Übereinstimmungen liefern und keine Präzisionsanpassungen wie bei Gleitkommazahlen (decimal, quantity) vornehmen. Der FHIR Data Service MUSS für Suchanfragen, die Range- oder Period-Werte betreffen, sicherstellen, dass obere und untere Grenzen des Bereichs korrekt berücksichtigt werden und mit den definierten Vergleichspräfixen korrekt verarbeitet werden.

Beispiele:

Alle AuditEvents, die vor dem 15. Januar 2025 aktualisiert oder erstellt wurden:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_lastUpdated=lt2025-15-01T00:00:00Z


Alle AuditEvents nach dem 15. Januar 2025:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?date=gt2025-15-01T00:00:00Z


Alle AuditEvents seit dem 15. Januar 2025 und von der Allgemeinarztpraxis “Praxis Dr. John Doe”:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?date=ge2025-15-01T11:00:00Z&altid=1-883110000092404


Alle AuditEvents ab dem 15. Januar 2025 und alle AuditEvents, die eine Erstellung protokollieren:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?date=2025-15-01T11:00:00Z&action=C


Alle AuditEvents für das XDS-Dokument Arztbrief4711:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?entity-name=Arztbrief4711


Sortierung

Das ePA-Client-System KANN die Reihenfolge der zurückgegebenen Ergebnisse durch den Parameter _sort angeben, der eine durch Kommas getrennte Liste von Sortierregeln in Prioritätsreihenfolge enthalten kann. Der FHIR Data Service MUSS die Sortierfunktion nach FHIR R4 Sorting implementieren.

Beispiel:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_sort=action,-date