Interfaces Resource Broker VnC
De waarde van de base-URL ( [base] ) van de FHIR endpoints die de Resource Broker VnC biedt , dient voor alle FHIR-interacties gelijk te zijn aan "https://<FQDN>{</path extension>}/fhir/<fhir-version>". De waarde van <fhir-version> is dan bijvoorbeeld "R4" of "R5".
Verzending & Consolidatie Interface
Deze interface is slechts bedoeld voor gebruik door VZVZ-componenten, en kan niet (rechtstreeks) worden gebruikt door GBx-applicaties.
De Verzending & Consolidatie Interface ondersteunt de volgende versies van het AORTA access_token:
versie 1.1 (AoF 0.6)
versie 2.0 (AoF 0.7)
versie 3.*
versie 4.*
Reguliere FHIR-interactie
Feature | |
|---|---|
Type | Abstracte Service |
Versie | 1.5.1 |
Systeemrolcode | - |
Groep | Broker |
Gepubliceerd |
|
Delta | De base-URL van de Transformatie Server dient te worden verkregen uit het AORTA Stelseltoken. |
Use case |
Feature | Versie | Dependency | Aanbieder | Afnemer |
|---|---|---|---|---|
1.5.1 | >=1.* | >=1.* |
De Verzending & Consolidatie Interface is voor reguliere FHIR-interacties (search, read, update, batch/transaction) nagenoeg gelijk aan de AORTA FHIR Resource Interface. Dit geldt zowel voor het generieke deel van de interface als voor de AORTA FHIR * interacties. In deze sectie worden daarom slechts de afwijkingen hierop beschreven.
M.b.t. de HTTP headers die worden gebruikt gelden voor alle interacties de volgende extra headers:
Conditionele request header:
DigiD-Authenticatie: Bearer <authenticatietoken>
Een request die is gestuurd door een patiënt (via MedMij of een GBP) dient altijd een DigiD-Authenticatie header te bevatten.
Vooralsnog hoeven slechts JWT-based access_tokens, en SAML-based authenticatietokens te worden ondersteund.
Een token dat wordt meegezonden is in sommige gevallen een XML SAMLv2 Assertion, en in andere situaties een JSON Web Token (JWT). Een JWT bestaat uit een aantal base64 strings, die aan elkaar zijn gekoppeld met punten. Omdat een base64url geëncodeerde SAMLv2 Assertion geen punten kan bevatten, is de ontvanger altijd in staat om het type token bepalen.
Een SAML Assertion dient altijd base64url te worden gecodeerd conform RFC 4648.
get-aorta-data
Feature | |
|---|---|
Type | Service |
Versie | 1.4.1 |
Systeemrolcode | - |
Groep | Broker |
Gepubliceerd |
|
Delta | De base-URL van de Transformatie Server dient te worden verkregen uit het AORTA Stelseltoken. |
Use case |
Feature | Versie | Dependency | Aanbieder | Afnemer |
|---|---|---|---|---|
1.4.1 | >=* | >=* | ||
1.4.1 | AORTA-ID HTTP Header | >=1.0.0 | >=1.0.0 | |
1.4.1 | Authorization HTTP Header | >=1.0.0 | >=1.0.0 | |
1.4.1 | >=* | - | ||
1.4.1 | >=* | - | ||
1.4.1 | >=1.0.0 | - |
Via een get-aorta-data request kunnen gegevens worden opgehaald bij GBZ-applicaties die zijn aangesloten op het AORTA netwerk.
Het technische formaat van een protocol-agnostisch get-aorta-data request is:
POST [base endpointadres]/get-aorta-data/v1Authorization: Bearer <AORTA access_token>Content-Type: application/json; charset=utf-8AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122> { "protocol": "", "context": "", "destination": "", "effective-time": ["",""], "therapy-identifier": "", "classifier": "", "instance-identifier": ""}
Bij het verzenden van een protocol-agnostisch get-aorta-data request dienen de volgende HTTP headers te worden meegezonden:
Feature | Authorization HTTP Header |
|---|---|
Type | Subfeature |
Versie | 1.0.0 |
Systeemrolcode | - |
Groep | HTTP Headers |
Gepubliceerd |
|
Delta | Initiële versie van feature. |
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.
Content-Type: application/json; charset=utf-8
Feature | AORTA-ID HTTP Header |
|---|---|
Type | Subfeature |
Versie | 1.0.0 |
Systeemrolcode | - |
Groep | HTTP Headers |
Gepubliceerd |
|
Delta | Initiële versie van feature. |
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.
Input parameters:
Name | Cardinality | Type | Toelichting |
protocol | 1..1 | String | Het gevraagde protocol in de response. Mogelijke waarden:
|
context | 1..1 | String | AORTA contextcode waarbinnen de operation wordt uitgevoerd. Bijvoorbeeld:
|
destination | 0..1 | String | URA van de zorgaanbieder die bevraagd moet worden, of het applicatieID van de Resource Server (GBZ-applicatie) die bevraagd moet worden. Wanneer de destination afwezig is, dan worden alle Resource Server waarvoor toestemming is geregistreerd bevraagd. Formaat:
|
effective-time | 0..1 | String array | De periode waarop een geregistreerd gegeven betrekking heeft (bijv. medisch of logistiek relevant is). Bijvoorbeeld:
|
therapy-identifier | 0..1 | String | Een business identifier van een specifieke behandeling. Bijvoorbeeld:
|
classifier | 0..1 | String | Typering van bijv. het soort medicatie, observaties, diagnoses of problemen. Bijvoorbeeld:
|
instance-identifier | 0..1 | String | Een business identifier van een specifieke bouwsteen instantie. Bijvoorbeeld:
|
Het technische formaat van een get-aorta-data response is:
200 OKContent-Type: application/json; charset=utf-8
{ "format": "", "result": ""}
Bij het verzenden van een protocol-agnostische get-aorta-data response dienen de volgende HTTP headers te worden meegezonden:
Content-Type: application/json; charset=utf-8
Output parameters:
push-aorta-data
Feature | |
|---|---|
Type | Service |
Versie | 1.2.1 |
Systeemrolcode | - |
Groep | Broker |
Gepubliceerd |
|
Delta | De base-URL van de Transformatie Server dient te worden verkregen uit het AORTA Stelseltoken. |
Use case |
Feature | Versie | Dependency | Aanbieder | Afnemer |
|---|---|---|---|---|
1.2.1 | >=* | >=* | ||
1.2.1 | AORTA-ID HTTP Header | >=1.0.0 | >=1.0.0 | |
1.2.1 | Authorization HTTP Header | >=1.0.0 | >=1.0.0 | |
1.2.1 | >=* | - | ||
1.2.1 | >=* | - | ||
1.2.1 | >=1.0.0 | - |
Via een push-aorta-data request kunnen gegevens worden verzonden naar GBZ-applicaties die zijn aangesloten op het AORTA netwerk.
Het technische formaat van een protocol-agnostisch push-aorta-data request is:
POST [base endpointadres]/push-aorta-data/v1Authorization: Bearer <AORTA access_token>Content-Type: application/json; charset=utf-8AORTA-ID: initialRequestID=<UUID conform RFC4122>; requestID=<UUID conform RFC4122>
{ "protocol":"", "context":"" "destination":"", "format": "", "data": ""}
Bij het verzenden van een protocol-agnostisch push-aorta-data request dienen de volgende HTTP headers te worden meegezonden:
Feature | Authorization HTTP Header |
|---|---|
Type | Subfeature |
Versie | 1.0.0 |
Systeemrolcode | - |
Groep | HTTP Headers |
Gepubliceerd |
|
Delta | Initiële versie van feature. |
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.
Content-Type: application/json; charset=utf-8
Feature | AORTA-ID HTTP Header |
|---|---|
Type | Subfeature |
Versie | 1.0.0 |
Systeemrolcode | - |
Groep | HTTP Headers |
Gepubliceerd |
|
Delta | Initiële versie van feature. |
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.
Input parameters:
Name | Cardinality | Type | Toelichting |
protocol | 1..1 | String | Het gehanteerde protocol. Mogelijke waarden:
|
context | 1..1 | String | Code van de context waarbinnen de operation wordt uitgevoerd. Bijvoorbeeld:
|
destination | 1..1 | String | URA van de zorgaanbieder, of het applicatieID van de Resource Server (GBZ-applicatie) waarnaar de gegevens verzonden moeten worden. Formaat:
NB. vooralsnog dient destination gevuld te zijn met een applicatieID. |
format | 1..1 | Lege string of een string met waarde escape of base64. | Gehanteerde encodering voor |
data | 1..1 | String waarop de benodigde escaping is toegepast, of die base64 geëncodeerde data bevat. | De inhoud van de push interactie (v3-request of FHIR-request). |
Het technische formaat van een push-aorta-data response is:
<HTTP statuscode returned by destination>Content-Type: application/json; charset=utf-8<any other HTTP headers returned by destination>
{ "format": "", "result": ""}
Bij het verzenden van een protocol-agnostische push-aorta-data response dienen de volgende HTTP headers te worden meegezonden:
Content-Type: application/json; charset=utf-8
Output parameters:
Name | Cardinality | Type | Toelichting |
format | 1..1 | Lege string of een string met waarde escape of base64. | Gehanteerde encodering voor |
result | 0..1 | String waarop de benodigde escaping is toegepast, of die base64 geëncodeerde data bevat. | Afhankelijk van de waarde van protocol in het push-aorta-data request betreft het een v3-response of een FHIR-response. |
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.
AOF.UCe.VAL.100.v1 - Toetsing type content | Uitkomst | |
|---|---|---|
Stap | Omschrijving | |
i | Het systeem ontvangt een verzoek en start de verwerking. Het systeem toetst of het gevraagde type content (Accept header) en het gehanteerde type content (Content-Type header) worden ondersteund. NB. wanneer het verzoek wordt ontvangen van een component van VZVZ, dan hoeft geen toets op type content te worden uitgevoerd. | Gevraagd type content niet ondersteund statuscode 406 Not Acceptable |
Gehanteerd type content niet ondersteund statuscode 415 Unsupported Media Type | ||
Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow. | ||
Stap | Omschrijving | Uitkomst |
|---|---|---|
1 | Het systeem controleert de geldigheid van het AORTA access_token, zoals omschreven in de toelichting Controle en gebruik van het access_token. | Ongeldig token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow. | ||
2 | Het systeem toetst of het verzoek voldoet aan de interface specificatie. | Ongeldig FHIR-verzoek statuscode 400 Bad Request
|
Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow. | ||
3 | Indien het request een pull-interactie betreft: Het systeem verifieert of de gevraagde gegevens mogen worden opgeleverd, zoals omschreven in de "Toelichting beschikbaarstelling". Het systeem verwerkt de interactie conform de implementatiehandleiding, zoals benoemd in de sectie Informatiestandaard specifieke verwerking van requests. Het systeem zorgt ervoor dat bij eventueel op te leveren Patient resource instances de identifier is gevuld met het BSN van de betroffen persoon, zoals beschreven in de “Toelichting vulling BSN bij opleveren van gegevens”. Indien het request een verzoek om (een) PDF/A document(en) betreft: Het systeem zorgt ervoor dat slechts (referenties naar) documenten worden geretourneerd die behoren tot de set van ondersteunde mimetypes. Het systeem zorgt ervoor dat wordt voldaan aan de “Toelichting vulling content.attachment.url". | Gevraagde gegevens mogen niet worden opgeleverd statuscode 403 Forbidden
|
Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow. | ||
4 | Indien het request een push-interactie betreft: Het systeem verifieert of de interactie mag worden verwerkt. Het systeem verwerkt de interactie conform de implementatiehandleiding, zoals benoemd in de sectie Informatiestandaard specifieke verwerking van requests. Het systeem verwerkt bij eventueel ontvangen Patient resource instances ook de identifier die is gevuld met het BSN van de betroffen persoon, zoals beschreven in de “Toelichting vulling BSN bij ontvangen van gegevens”. | Onjuiste autorisatie statuscode 403 Forbidden
|
5 <exit> | Het systeem retourneert een response naar de primaire actor. | Verwerking succesvol statuscode 200 OK
Voor bovenstaande criteria geldt dat ze
|
Verwerking succesvol - resource instance gecreëerd statuscode 201 Created |
AOF.UCe.VAL.100.v1 - Toetsing type content | Uitkomst | |
|---|---|---|
Stap | Omschrijving | |
i | Het systeem ontvangt een verzoek en start de verwerking. Het systeem toetst of het gevraagde type content (Accept header) en het gehanteerde type content (Content-Type header) worden ondersteund. NB. wanneer het verzoek wordt ontvangen van een component van VZVZ, dan hoeft geen toets op type content te worden uitgevoerd. | Gevraagd type content niet ondersteund statuscode 406 Not Acceptable |
Gehanteerd type content niet ondersteund statuscode 415 Unsupported Media Type | ||
Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow. | ||
Stap | Omschrijving | Uitkomst |
|---|---|---|
1 | Het systeem controleert de geldigheid van het AORTA access_token, zoals omschreven in de toelichting Controle en gebruik van het access_token. | Ongeldig token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow. | ||
2 | Het systeem toetst of het verzoek voldoet aan de interface specificatie. | Ongeldig FHIR-verzoek statuscode 400 Bad Request
|
Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow. | ||
3 | Indien het request een pull-interactie betreft: Het systeem verifieert of de gevraagde gegevens mogen worden opgeleverd, zoals omschreven in de "Toelichting beschikbaarstelling". Het systeem verwerkt de interactie conform de implementatiehandleiding, zoals benoemd in de sectie Informatiestandaard specifieke verwerking van requests. Het systeem zorgt ervoor dat bij eventueel op te leveren Patient resource instances de identifier is gevuld met het BSN van de betroffen persoon, zoals beschreven in de “Toelichting vulling BSN bij opleveren van gegevens”. Indien het request een verzoek om (een) PDF/A document(en) betreft: Het systeem zorgt ervoor dat slechts (referenties naar) documenten worden geretourneerd die behoren tot de set van ondersteunde mimetypes. Het systeem zorgt ervoor dat wordt voldaan aan de “Toelichting vulling content.attachment.url". | Gevraagde gegevens mogen niet worden opgeleverd statuscode 403 Forbidden
|
Het systeem genereert de vereiste response en gaat verder met de exit stap van de main flow. | ||
4 | Indien het request een push-interactie betreft: Het systeem verifieert of de interactie mag worden verwerkt. Het systeem verwerkt de interactie conform de implementatiehandleiding, zoals benoemd in de sectie Informatiestandaard specifieke verwerking van requests. Het systeem verwerkt bij eventueel ontvangen Patient resource instances ook de identifier die is gevuld met het BSN van de betroffen persoon, zoals beschreven in de “Toelichting vulling BSN bij ontvangen van gegevens”. | Onjuiste autorisatie statuscode 403 Forbidden
|
5 <exit> | Het systeem retourneert een response naar de primaire actor. | Verwerking succesvol statuscode 200 OK
Voor bovenstaande criteria geldt dat ze
|
Verwerking succesvol - resource instance gecreëerd statuscode 201 Created |
Aanvullende eisen
AOF-I.GEN.100.v1 - Gebruik van GZN
De interface wordt aangeboden op AORTA-net, dus via een GZN.
AOF-I.GEN.110.v1 - Gebruik van veilig intern netwerk
De interface wordt aangeboden op een beveiligd besloten netwerk dat ter beschikking staat voor communicatie tussen componenten onderling, en tussen componenten en de ZIM.
AOF-I.GEN.150.v1 - Gebruik van HTTP
HTTP-requests en -responses op deze interface worden verzonden conform HTTP versie 1.1.
Alle HTTP-verkeer wordt verzonden binnen een TLS verbinding.
AOF-I.GEN.200.v1 - TLS verbindingen
TLS clients en TLS servers dienen tenminste TLS versie 1.2 te ondersteunen en mogen hierbij slechts gebruik maken van algoritmeselecties uit de categorie "Goed", zoals genoemd in bijlage C van de ICT-beveiligingsrichtlijnen voor Transport Layer Security (TLS).
Bij het opzetten van een verbinding dient gebruik te worden gemaakt van de sterkste algoritmeselectie die door beide partijen wordt ondersteund. TLS clients en TLS servers maken bij voorkeur echter gebruik van een hogere TLS versie dan 1.2.
Binnen TLS verbindingen dienen tijdelijke sleutels te worden toegepast, die elke 5 minuten worden ververst door middel van TLS Secure Renegotiation.
TLS verbindingen worden opgezet middels PKIo servercertificaten of, voor zorgaanbieders, m.b.v. UZI-servercertificaten.
AOF-I.GEN.250.v1 - Systeem Authenticatie (mTLS)
Indien uitwisseling plaatsvindt binnen TLS verbindingen, dan dient op deze interface gebruik te worden gemaakt van tweezijdige authenticatie (mutual TLS, mTLS), waarbij de TLS client en de TLS server zich wederzijds authenticeren.
AOF-I.GEN.400.v1 - FHIR
Op deze interface gelden de generieke eisen uit de MedMij informatiestandaarden. Dit betekent ondermeer dat zowel JSON als XML moet worden ondersteund.
AOF-I.GEN.450.v1 - Verkrijgen base-URL van component
Deze interface wordt geboden door een component die is opgenomen in het AORTA Stelseltoken. In de specificaties is aangegeven welke component het betreft.
Wanneer deze interface wordt gebruikt via HTTP, dan mag deze slechts worden gericht aan de base-URL van een server/component die deze rol blijkens het AORTA Stelseltoken vervuld.
Het geldende AORTA Stelseltoken dient periodiek te worden opgehaald via de AORTA Stelsel Metadata Interface. De aangeven caching directives dienen hierbij te worden gevolgd.