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

Query API: Allgemeine Anforderungen Paginierung

Bei einer Suche im FHIR Data Service über die FHIR Query API stellt der Service dem ePA-Client-System in seiner Antwort ggf. Links zu weiteren Ergebnissen zur Verfügung, die es dem Client erlauben, bequem durch die Ergebnismenge zu navigieren.

Der FHIR Data Service MUSS eine Paginierungsfunktion implementieren und in seiner Antwort Navigationsinformationen in Ergebnisseiten zur Verfügung stellen. Um die Paginierungsfunktion zu implementieren, werden die URL-Parameter _count und _offset verwendet. Der Parameter _count bestimmt die Anzahl der Einträge pro Seite (page), während _offset das Startelement der Seite angibt. Zusätzlich entscheidet der _total-Parameter, ob die Gesamtanzahl der Einträge in der Antwort enthalten sein soll.

URL-Parameter Beschreibung Standardwert
_count Das ePA-Client-System KANN die maximale Anzahl von Elementen festlegen, die auf einer Seite (page) der Antwort enthalten sein soll. Das bedeutet, dass der Audit Event Service die Ergebnismenge auf diese maximal angegebene Anzahl beschränkt. 25
_offset Dieser Parameter gibt den (zero-based) Offset des ersten zurückgegebenen Elements in der Sammlung an. 0
_total Dieser Parameter steuert, ob und wie der Audit Event Service die Gesamtanzahl der Suchergebnisse zurückgibt. Folgende Werte können eingestellt werden: none, estimate, accurate. -
Tabelle: URL-Parameter für Paginierungsfunktion

Werte für _total:

  • none (Standardwert): Die Gesamtanzahl der Suchtreffer wird nicht angezeigt.
  • estimate: Die ungefähre Gesamtanzahl der Suchtreffer wird angezeigt.
  • accurate: Die genaue Gesamtanzahl der Suchtreffer wird angezeigt.

Beispiele:

API-Anfrage von zehn Elementen des Ressourcentyps AuditEvent, beginnend mit Element 20 der Liste:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_count=10&_offset=20


API-Anfrage der ersten fünf Elemente:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_count=5


API-Anfrage nur für die Gesamtanzahl der Einträge:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_count=0&_total=accurate


Der FHIR Data Service MUSS in einem FHIR Search Set Bundle das FHIR-Element link belegen, welches eine Liste von Link-Elementen beinhaltet, welche jeweils einem spezifischen Navigationszweck innerhalb des FHIR Bundles dienen.

Die folgenden Beziehungen werden gemäß den Link Relation Types bereitgestellt.

Link Relation Beschreibung Anforderung
self Ein Link zur aktuellen Seite der Ergebnisse, der die Abfrage repräsentiert, die diese Ergebnisse generiert hat. MUSS
next Wird verwendet, um zur nächsten Seite der Ergebnisse zu navigieren, entsprechend der festgelegten Paginierung. MUSS
previous Ermöglicht die Rückkehr zur vorherigen Ergebnismenge und erleichtert die rückwärtige Navigation durch die Seiten. MUSS
first Navigiert zur ersten Seite der Suchergebnisse und ermöglicht eine schnelle Navigation zum Anfang der Ergebnisliste. KANN
last Navigiert zur letzten Seite der Suchergebnisse, um ans Ende der Ergebnisliste zu gelangen. KANN
Tabelle: Seitennavigationslinks für Paginierungsfunktion

Jeder Link MUSS eine URL enthalten, um das entsprechende Ergebnis-Set abzurufen, das dynamisch basierend auf der Suchanfrage und den Paginierungsparametern wie _count und _offset generiert wird. Diese Links vereinfachen die Navigation eines ePA-Client-Systems durch große Suchergebnisse, indem sie die Notwendigkeit manueller Anpassungen der Abfrageparameter ausräumt. Der FHIR Data Service KANN beim Paginieren von FHIR-Bundles das Feld Bundle.link.url mit relativen URLs befüllen, sofern diese sich auf die Basis-URL beziehen.

Zu jedem Link können zusätzlich zu den Standardpaginierungsparametern wie _count und _offset auch andere Parameter enthalten sein, die die Paginierung innerhalb des FHIR Data Service erleichtern. Ein Beispiel hierfür ist der Parameter stateid, der den aktuellen Zustand der Ergebnisliste repräsentiert. Dies ermöglicht es dem FHIR Data Service, die Navigation durch die Ergebnisse effizient zu verwalten, indem der Kontext oder Zustand der Suche erhalten bleibt. Dies ist besonders nützlich, wenn ePA-Clients durch umfangreiche oder komplex strukturierte Ergebnismengen navigieren.

Beispiel (Audit Event Service):

{
    "resourceType": "Bundle",
    "id": "86604fc1-b356-57e3-8738-8ef36c8d608c",
    "type": "searchset",
    "total": 100,
    "link": [
    {
        "relation": "self",
        "url": "/epa/audit/api/v1/fhir/AuditEvent?_count=10&_offset=20"
    },
    {
        "relation": "first",
        "url": "/epa/audit/api/v1/fhir/AuditEvent?_count=10&_offset=0"
    },
    {
        "relation": "previous",
        "url": "/epa/audit/api/v1/fhir/AuditEvent?_count=10&_offset=10"
    },
    {
        "relation": "next",
        "url": "/epa/audit/api/v1/fhir/AuditEvent?_count=10&_offset=30"
    },
    {
        "relation": "last",
        "url": "/epa/audit/api/v1/fhir/AuditEvent?_count=10&_offset=90"
    }
    ],
    "entry": [
    {
        "fullUrl": "http://epa4all/epa/audit/api/v1/fhir/AuditEvent/5abff610-a1ad-450d-aa63-a60622b1052e",
        "resource": {
        "resourceType": "AuditEvent",
        "id": "5abff610-a1ad-450d-aa63-a60622b1052e",
        // Details of the AuditEvent resource
        }
    },
    // More AuditEvent entries
    ]
}