Interfaces Resource Server

HL7-FHIR Resource Server

Generiek voor alle FHIR resource server interfaces

De volgende eisen gelden voor alle interfaces van de resource server:

1. De waarde van de base-URL van de FHIR endpoints die een resourceserver biedt ( [base] dus ), dient voor alle FHIR-interacties gelijk te zijn aan:

   1. Indien <fhir-version> gelijk is aan STU3: https://<FQDN>/fhir, dus bijvoorbeeld "http://myhost.customer.org/fhir"

   2. Indien <fhir-version> hoger dan STU3: https://<FQDN>/fhir/<fhir-version>, dus bijvoorbeeld "http://myhost.customer.org/fhir/R4"

De waarde van <fhir-version> is dan bijvoorbeeld "R4" of "R5".

AORTA CapabilityStatement Interface

Resource server biedt op zijn endpoint een CapabilityStatement aan. Een resource client kan het statement als volgt bij de resource server opvragen:

GET [base]/metadata {?_format=[mime-type]}

Het gaat hier om een CapabilityStatement van het type "Instance", oftewel het bevat informatie over de daadwerkelijke installatie die benaderbaar is. Bovenstaande capabilities interactie is binnen FHIR verplicht voor FHIR servers en dient binnen AORTA als een equivalent van de Ping-Pong interactie in HL7v3.

Let op: de capabilities interactie wordt geboden in de <fhir-version> die geldt voor het betreffende endpoint.

Op deze interface worden de additionele HTTP headers, die gelden voor de AORTA FHIR Resource Interface, NIET toegepast.

HTTP statuscodes

HTTP statuscodes die kunnen worden geretourneerd zijn:

AORTA FHIR Resource Interface

Generiek

Via de AORTA Resource Interface kunnen verschillende services worden aangeroepen op een resource server. Deze services zijn in een use case formaat omschreven op de UC Resource Server pagina. Op deze pagina wordt voor iedere service verwezen naar de van toepassing zijnde implementatiehandleiding, zoals opgesteld en beheerd door Nictiz.

Ten opzichte van de Nictiz implementatiehandleidingen gelden voor alle interacties de volgende uitzonderingen:

• Wanneer een Bundle wordt gePOST, conform een specifiek FHIR-profiel, bijvoorbeeld "mp-MedicationPrescription-Bundle", dan dient Bundle.meta.profile te zijn gevuld met de juiste canonical.

Bij iedere interactie, worden in ieder HTTP-request, de volgende HTTP headers meegezonden:

Authorization: Bearer <AORTA access_token>

Een AORTA access_token is altijd een JSON Web Token (JWT).

Een JWT bestaat uit een aantal base64 strings, die aan elkaar zijn gekoppeld met punten. Indien een token een SAML Assertion zou zijn, dan dient het altijd base64url te worden gecodeerd conform RFC 4648. Omdat een base64url geëncodeerde SAMLv2 Assertion geen punten kan bevatten, is de ontvanger altijd in staat om het type token bepalen.

In het token, dat wordt ontvangen in een Authorization header, is informatie opgenomen over welke type inhoudelijk token het betreft en welke versie, dus bijvoorbeeld dat het gaat om een AORTA access_token.

AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122>

Het initialRequestID attribuut bevat het ID van het allereerste request in de hele keten en dient te worden opgenomen in de logbestanden van alle partijen in de keten, zodat bij foutopsporing de verschillende logbestanden aan elkaar kunnen worden gerelateerd.

Het requestID is voor iedere request message uniek. In requests wordt deze gegenereerd door de client. Ook het requestID dient te worden opgenomen in de verschillende logbestanden, zodat altijd duidelijk is op welk bericht een log entry van toepassing is.

AORTA-Version: contentVersion=<versienummer>; acceptVersion=<versienummer>

Wanneer een Resource Server een FHIR interactie ontvangt, dan kan het a.d.h.v. de syntax van het ontvangen request afleiden om welke interactie het gaat, bijvoorbeeld "een FHIR-search naar Obervations", of "een FHIR-read van een Binary". Daarnaast is iedere interactie voorzien van een versienummer. Voor versienummering wordt gebruik gemaakt van semantic versioning.

De acceptVersion geeft aan conform welke versie(s) de interactie mag worden verwerkt en beantwoord. Het versienummer in de acceptVersion wordt gespecificeerd conform semver, dus bijvoorbeeld "2.x" of "~1.2.3 || ^2.1.0". In het algemeen geldt dat een resource server een interactie dient te verwerken conform de hoogst aangegeven acceptVersion die het zelf op dat moment kan toepassen.

De contentVersion geeft aan welke versie van de interactie daadwerkelijk is gehanteerd. In de contentVersion dient het versienummer de exacte versie van de interactie te bevatten die is gehanteerd, dus zonder wildcards of ranges, bijvoorbeeld “1”, of "2.2". De versie van een FHIR-interactie is opgenomen in het interactie-id.

Bij iedere interactie, worden in iedere HTTP-response, de volgende HTTP headers meegezonden:

AORTA-Version: contentVersion=<versienummer>

De contentVersion geeft aan welke versie van de interactie daadwerkelijk is gehanteerd. In de contentVersion dient het versienummer de exacte versie van de interactie te bevatten die is gehanteerd, dus zonder wildcards of ranges, bijvoorbeeld “1”, of "2.2". De versie van een FHIR-interactie is opgenomen in het interactie-id.

NB. voor Resource Servers (GBZ-applicaties) is het opnemen van een AORTA-Version Header in HTTP-responses optioneel. Resource Broker componenten zullen deze header wel retourneren, en zo nodig dus zelf met het juiste versienummer vullen.

Encodering van pipe symbolen

Wanneer zoekparameters van het type uri worden gebruikt, dan dienen eventuele "|" symbolen conform RFC 3986 te worden geëncodeerd. De Resource Broker componenten encoderen "|" symbolen in FHIR interacties die zij verzenden. Resource Broker MedMij-in dient echter ook om te kunnen gaan met situaties waarbij een PGO Server een "|" symbool niet encodeert.

Zie ook de vraag die hierover is gesteld in BITS.

AORTA FHIR read

De resource client initieert een FHIR read interactie bij de resource server en gebruikt hiervoor de HTTP GET Method op de volgende wijze:

GET [base]/[type]/[id]

Waarbij [type] het FHIR resourcetype aangeeft. Middels [id] wordt de juiste resource instance (op het betreffende FHIR endpoint) geïdentificeerd.

AORTA FHIR search

De resource client initieert een FHIR search interactie bij de resource server en gebruikt hiervoor de HTTP GET Method op de volgende wijze:

GET [base]/[type]{?[parameters]}

Waarbij [type] het FHIR resourcetype aangeeft. Middels [parameters] kan de zoekopdracht worden verfijnd.

AORTA FHIR create

De resource client initieert een FHIR create interactie bij de resource server en gebruikt hiervoor de HTTP POST Method op de volgende wijze:

POST [base]/[type]

Waarbij [type] het FHIR resourcetype aangeeft.

Wanneer de resource succesvol kan worden gecreëerd, dan retourneert de resource server ook de volgende location header:

• Location: [base]/[type]/[id]/_history/[vid]

Waarbij [id] en [vid] het resource.id en het versie id zijn van de zojuist gecreëerde resource instance.

AORTA FHIR update

De resource client initieert een FHIR update interactie bij de resource server en gebruikt hiervoor de HTTP PUT Method op de volgende wijze:

PUT [base]/[type]/[id]

Waarbij [type] het FHIR resourcetype aangeeft. Middels [id] wordt de juiste resource instance (op het betreffende FHIR endpoint) geïdentificeerd.

AORTA FHIR batch/transaction

De resource client initieert een FHIR batch/transaction interactie bij de resource server en gebruikt hiervoor de HTTP POST Method op de volgende wijze:

POST [base]

De inhoud van de POST is een FHIR Bundle van het type batch of transaction. Iedere Entry in de Bundle bevat een specifiek FHIR interactie die moet worden uitgevoerd.

Binnen AORTA kan een resource server afzonderlijk worden gekwalificeerd en geaccepteerd voor een AORTA FHIR batch interactie en voor een AORTA FHIR transaction interactie.

Ondersteunde FHIR interacties binnen een batch type Bundle:

• AORTA FHIR create.

Ondersteunde FHIR interacties binnen een transaction type Bundle:

• AORTA FHIR create;

• AORTA FHIR update.

Deze sets zullen in de loop van de tijd worden uitgebreid.

Interacties die zijn opgenomen in de Bundle dienen afzonderlijk te worden verwerkt conform de specificaties van de betreffende interactie. Daarnaast gelden de algemene FHIR verwerkingsregels voor batch en transaction type Bundles.

De HTTP-headers, zoals de Authorization, AORTA-ID en AORTA-Version headers gelden voor de gehele batch/transaction en zijn daarmee van toepassing op alle individuele interacties die zijn opgenomen in de Bundle.

AORTA FHIR $is-allowed

De resource server ondersteunt op haar endpoint een custom FHIR operation, waarmee een resource client kan achterhalen of een zorgaanbieder:

• bepaalde gegevens, los van het feit of deze gegevens daadwerkelijk aanwezig zijn, beschikbaar stelt voor opvraag door een specifieke patiënt (middels een "verzamel-gegevensdienst"), danwel

• ontvankelijk is voor bepaalde gegevens die een specifieke patiënt haar wenst te sturen (middels een "delen-gegevensdienst"). Hierbij dienen tenminste de ontvankelijkheidscriteria te worden getoetst die zijn gespecificeerd in het MedMij afsprakenstelsel.

Een resource server dient een beschikbaarheids- of ontvankelijkheidsvraag te kunnen beantwoorden voor alle MedMij Verzamelen en Delen gegevensdiensten waarvoor het een rol vervult.

Een resource client kan de beschikbaarheid- of ontvankelijkheidstatus als volgt ophalen:

GET [base]$is-allowed?scope=<scope aanduiding>

Het BSN van de betreffende patient is opgenomen in het access_token.

Voorbeeld $is-allowed

HTTP request:

GET [base]$is-allowed?scope=http://fhir.nl/fhir/NamingSystem/medmij-scope|eenofanderezorgaanbieder~53 HTTP/1.1

XML-based HTTP response wanneer gebruik gegevensdienst is toegestaan:

200 OK

[andere headers]

<?xml version="1.0" encoding="UTF-8"?>

<OperationOutcome xmlns="http://hl7.org/fhir">

<id value="0e855422-b8ef-4247-9443-f3747e78747e"/>

<issue>

<severity value="information"/>

<code value="informational"/>

<diagnostics value="http://fhir.nl/fhir/NamingSystem/medmij-scope|eenofanderezorgaanbieder~53"/>

</issue>

</OperationOutcome>

XML-based HTTP response wanneer gebruik van een delen-gegevensdienst niet is toegestaan:

200 OK

[andere headers]

<?xml version="1.0" encoding="UTF-8"?>

<OperationOutcome xmlns="http://hl7.org/fhir">

<id value="0e855422-b8ef-4247-9443-f3747e78747e"/>

<issue>

<severity value="information"/>

<code value="forbidden"/>

</issue>

</OperationOutcome>

JSON-based HTTP response wanneer gebruik van een verzamelen-gegevensdienst niet is toegestaan:

200 OK

[andere headers]

{

"resourceType": "OperationOutcome",

"id": "0e855422-b8ef-4247-9443-f3747e78747e",

"issue": [{

"severity": "information",

"code": "suppressed"

}]

}

AORTA FHIR pull-notification

HTTP statuscodes

HTTP statuscodes die kunnen worden geretourneerd zijn opgenomen in onderstaande tabel.

Omdat bepaalde Confluence macro’s nog niet worden ondersteund in de publicatie omgeving, bevat de tabel, in de publicatieomgeving, ook informatie over de wijze waarop de betreffende interface wordt geïmplementeerd in de server component. De statuscodes die kunnen worden geretourneerd zijn opgenomen in de kolom “Uitkomst”. De overige informatie mag worden genegeerd.

Omgang met id, fullUrl en reference

De MedMij informatiestandaard stelt:

• When a client performs a search on a server, all instances in the returned searchset Bundle SHOULD have the id field populated.

  • Omitting ids is strongly discouraged as it breaks the assumptions about RESTful behavior. However, a server that omits ids is still considered conformant when the conditions below are met:

    • The server does not natively support logical ids

    • And the use case doesn't require read / update / delete / patch support for any of the returned of referenced resources, as stated by the CapabilityStatement for the information standard.

    • And the server includes all referenced resources in the searchset Bundle (regardless of whether the client asked to do so).

• When a client reads, updates or otherwise addresses an existing resource on a server, the id element SHALL be populated in the request and response, and it SHALL match the id in the request URL.

AORTA eis m.b.t. vulling van resource.id

Een FHIR resource die door een bronsysteem wordt opgeleverd in een search kan zijn voorzien van een id attribuut, binnen FHIR ook wel aangeduid als een logical id. Dit is een technische sleutel die geacht wordt uniek te zijn en hetzelfde te blijven binnen een resource server, zodat duplicaten eenduidig kunnen worden herkend. Het id attribuut is verplicht wanneer de implementatie van een informatiestandaard voor een gegevensdienst één of meerdere interacties bevat (bijvoorbeeld een read- of een update-interactie) waarvoor het resource.id attribuut nodig is.

Wanneer een resource server resource.id vult, dan dient deze te voldoen aan de eisen die FHIR stelt aan logical id's. 

De informatiestandaard stelt verder dat:

• If an instance can be accessed on the server using RESTful operations, the id of that instance in the Bundle will be populated. The corresponding fullUrl in this case SHALL be the absolute URL to the instance on the server.

• Instances within the Bundle may use relative references to each other, like they are on the same server.

• When id-less instances need to be referenced from within a Bundle, there are two alternatives:

  • UUIDs can be used as single-use ids that will change each time the Bundle is generated. The fullUrl for the instance will be the UUID prefixed with urn:uuid:

  • OIDs can be used if the instance has an OID-based business identifier (i.e. the identifier field), like the UZI number of a healthcare provider. The fullUrl will be the OID prefixed with urn:oid:

  • Instances within the Bundle should use the prefixed version of the UUID/OID for referencing.

De FHIR core standaard stelt dat:

• The fullUrl element SHALL have a value except that: * fullUrl can be empty on a POST (although it does not need to when specifying a temporary id for reference in the bundle) * Results from operations might involve resources that are not identified.

Iedere entry in een FHIR Bundle die wordt opgeleverd of verstuurd dient te voldoen aan bovenstaande eisen.

Vulling van bundle.entry.fullUrl en transformatie van URL's

Een absolute fullUrl, die wijst naar de instance op de server, is slechts vereist wanneer een resource instance in de Bundle middels een FHIR-read, FHIR-update, FHIR-patch of een FHIR-delete moet kunnen worden benaderd. Een fullUrl in de bundle entry wordt in andere situaties gevuld met een single-use UUID, of met een OID.

Wanneer een Resource Server een FHIR Bundle retourneert met een absolute URL (fullUrl of reference), dan dient deze URL het volgende formaat te hebben:

• <base endpointadres van Reagerend xIS>/<type>/<id>

Resource Broker MedMij-in of Resource Broker ZA-in transformeert de URL in deze situaties naar volgende formaat:

• <base endpointadres van Resource Broker XX-in>/<appID>/<type>/<id>

Waarbij het <type> het geretourneerde resource type bevat, bijvoorbeeld "Observation" en <appID> het applicatie-id (zonder root OID) bevat van het bronsysteem.

Bovenstaande aanpassing van absolute URL's is nodig, zodat een Resource Client, indien van toepassing binnen een gegevensdienst, in staat is om, o.b.v. de URL in het zoekresultaat, een FHIR-read, FHIR-update, FHIR-patch of een FHIR-delete uit te voeren via de Resource Broker.

Voorbeeld van een Bundle

Een voorbeeld van een Bundle die die het gebruik van id, fullUrl en reference illustreert is hieronder weergegeven.

<Bundle>

..

<Entry>

<fullUrl value="https://medmij-pgo.vzvz.nl/fhir/453782/Patient/4" />

<Patient>

<id value="4" />

..

</Patient>

</Entry>

<Entry>

<fullUrl value="urn:uuid:0e855422-b8ef-4247-9443-f3747e78747e" />

<Patient>

<!--  Onderstaande id mag op deze wijze worden gevuld, maar mag in deze situatie ook worden weggelaten -->

<id value="0e855422-b8ef-4247-9443-f3747e78747e" />

..

</Patient>

</Entry>

<Entry>

<fullUrl value="https://medmij-pgo.vzvz.nl/fhir/453782/Observation/10 />

<Observation>

<id value="10" />

<subject>

<reference value="Patient/4" />

</subject>

..

</Observation>

</Entry>

<Entry>

<fullUrl value="https://medmij-pgo.vzvz.nl/fhir/453782/Observation/11 />

<Observation>

<id value="11" />

<subject>

<reference value="urn:uuid:0e855422-b8ef-4247-9443-f3747e78747e" />

</subject>

..

</Observation>

</Entry>

<Entry>

<fullUrl value="https://medmij-pgo.vzvz.nl/fhir/453782/Observation/12 />

<Observation>

<id value="12" />

<subject>

<reference value="https://medmij-pgo.vzvz.nl/fhir/453782/Patient/5" />

</subject>

..

</Observation>

</Entry>

..

</Bundle>

HL7-v3 Resource Server

AORTA v3-interface

De interface specificaties zijn opgenomen in de HL7v3-Implementatiehandleidingen.