Resource Server Interfaces (versie 0.6.11 - definitief)

HL7-FHIR Resource Server

Generiek voor alle FHIR resource server interfaces

AOF.RS-I.GEN.100.v1

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: https://<FQDN>/fhir

AORTA CapabilityStatement Interface

AOF.RS-I.ACI.100.v1

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.

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

AORTA FHIR Resource Interface

Generiek

AOF.RS-I.FRI.100.v1

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:

• Het token dat dient te worden meegestuurd bij iedere FHIR-interactie is een AORTA access_token, zoals gespecificeerd op de pagina "Gemeenschappelijke interface onderdelen". Het token meegestuurd in een HTTP header: 
  Authorization: Bearer <token>

<token>, bevat een SAML-Assertion of het bevat een JWT. Vooralsnog worden slechts JWT-based access_tokens ondersteund.

De ontvanger ontvangt altijd het technisch type token dat het verwacht, dus een SAML2-based token of een JWT. In het token zelf is vervolgens informatie opgenomen over welke type inhoudelijk token het betreft en welke versie, dus dat het gaat om een AORTA access_token.

AOF.RS-I.FRI.200.v1

• Bij iedere interactie wordt in ieder HTTP-request, op de volgende wijze, een custom HTTP header meegezonden:
  AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122>
• Bij iedere interactie wordt in het HTTP-request op de volgende wijze een custom HTTP header meegezonden, met daarin de versie van de betreffende interactie die wordt gehanteerd in het request en de versie of versies die door de resource server mogen worden gehanteerd bij de verwerking van de interactie:
  AORTA-Version: contentVersion=<versienummer>; acceptVersion=<versienummer>
• Bij iedere interactie wordt in de HTTP-response op de volgende wijze een custom HTTP header meegezonden met daarin de door resource server daadwerkelijk gehanteerde versie en, indien transformatie heeft plaatsgevonden, het ID van het transformatie algoritme waarmee de response tot stand is gekomen:
  AORTA-Version: contentVersion=<versienummer>; transformationId=<ID van het gehanteerde transformatie algoritme>
  

AOF.RS-I.FRI.300.v1

Gebruik van de AORTA-ID header

Het initialRequestID attribuut bevat bevat het ID van het allereerste request in de hele keten van resource client tot resource server. Voor interacties vanuit het MedMij netwerk bevat het initialRequestID attribuut de waarde van het MedMij-Request-ID dat werd ingestuurd door de PGO server. Het initialRequestID dient te worden opgenomen in de logbestanden van alle partijen in de keten (Resource Client, Resource Broker, Transformatie Server en Resource Server), 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.

AOF.RS-I.FRI.400.v1

Gebruik van de AORTA-Version header

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". Iedere interactie is voorzien van een versienummer. Voor versienummering wordt gebruik gemaakt van semantic versioning.

Het versienummer in de acceptVersion wordt gespecificeerd conform semver, dus bijvoorbeeld "2.x" of "~1.2.3 || ^2.1.0". In de contentVersion dient het versienummer de exacte versie (naar keuze met of zonder patchnummer) te bevatten die is gehanteerd, dus zonder wildcards of ranges, bijvoorbeeld "2.2" of "2.3.2". De contentVersion geeft aan welke versie van de interactie daadwerkelijk is gehanteerd in de request of response. De acceptVersion geeft aan conform welke versie(s) de interactie mag worden verwerkt en beantwoord.

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. In de MedMij use case zal de acceptVersion  die wordt ingestuurd door Resource Broker MedMij-in in eerste instantie slechts één waarde bevatten.

AOF.RS-I.FRI.500.v1

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

AOF.RS-I.FRE.100.v1

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

AOF.RS-I.FSE.100.v1

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

AOF.RS-I.FCR.100.v1

Vooralsnog wordt een FHIR-create slechts ondersteund binnen een FHIR batch/transaction.

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.

AOF.RS-I.FCR.200.v1

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

AOF.RS-I.FUP.100.v1

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

AOF.RS-I.FBT.100.v1

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.

AOF.RS-I.FBT.200.v1

Ondersteunde FHIR interacties binnen een batch type Bundle:

• AORTA FHIR create.

AOF.RS-I.FBT.300.v1

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.

AOF.RS-I.FBT.400.v1

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

AOF.RS-I.ISA.100.v2

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.

AOF.RS-I.ISA.200.v1

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

AOF.RS-I.ISA.300.v1

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

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

AOF.RS-I.ISA.400.v1

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

AOF.RS-I.ISA.500.v1

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"

}]

}

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.

AOF.RS-I.IFR.100.v1

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 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.

AOF.RS-I.IFR.200.v1

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

AOF.RS-I.AV3.100.v1

De interface specificaties zijn opgenomen in de HL7v3-Implementatiehandleidingen waarnaar wordt verwezen de use case beschrijvingen in Use cases Resource Server.

{}