Interfaces Resource Broker GTK
AORTA CapabilityStatement Interface
Feature | |
---|---|
Type | Service |
Versie | 1.0.0 |
Groep | GTK |
Gepubliceerd |
|
Delta | Initiële versie van feature. NB. dit Feature is niet vereist wanneer RB GTK en RB VnC in dezelfde omgeving worden beheerd, EN het ook niet gaat worden vereist vanuit TWIIN. |
Use case |
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 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.
Stap | Omschrijving | Uitkomst |
---|---|---|
1 | Het systeem ontvangt een verzoek en start de verwerking. | |
2 | Het systeem toetst of het verzoek voldoet aan de interface specificatie. | Ongeldig verzoek statuscode 400 Bad Request |
Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow. | ||
3 <exit> | Het systeem retourneert een response naar de primaire actor. | Verwerking succesvol statuscode 200 OK |
AORTA FHIR Resource Interface
Feature | |
---|---|
Type | Service |
Versie | 1.0.0 |
Groep | GTK |
Gepubliceerd |
|
Delta | Initiële versie van feature:
|
Use case |
Feature | Versie | Dependency | Aanbieder | Afnemer |
---|---|---|---|---|
1.0.0 | * | * | ||
1.0.0 | AORTA-ID HTTP Header | * | * | |
1.0.0 | AORTA-Version HTTP Header | * | * | |
1.0.0 | Authorization HTTP Header | * | * | |
1.0.0 | Verplicht >=4.* | - | ||
1.0.0 | * | - |
Zie interface specificaties van de Resource Server.
FHIR interacties die worden ondersteund zijn:
AORTA FHIR create
AORTA FHIR read
AORTA FHIR update
AORTA FHIR search
AORTA FHIR batch/transaction
TWIIN FHIR Resource Interface
Feature | |
---|---|
Type | Service |
Versie | 1.0.0 |
Groep | GTK |
Gepubliceerd |
|
Delta | Initiële versie van feature:
|
Use case |
Feature | Versie | Dependency | Aanbieder | Afnemer |
---|---|---|---|---|
1.0.0 | * | - | ||
1.0.0 | AORTA-ID HTTP Header | * | - | |
1.0.0 | AORTA-Version HTTP Header | * | - | |
1.0.0 | Authorization HTTP Header | * | - | |
1.0.0 | Verplicht >=4.* | - | ||
1.0.0 | * | - |
Inkomend FHIR request
De waarde van de base-URL van de FHIR endpoints die het GTK biedt ( [base]
dus ), dient voor alle FHIR-interacties gelijk te zijn aan:
https://<FQDN>{</path extension>}/fhir/<fhir-version>/<twiin-interface-version>{/<app-id>}
De waarde van <fhir-version> is dan bijvoorbeeld "STU3", "R4" of "R5".
De waarde van <twiin-interface-version> is de major versie van de Technische Kern binnen Twiin die door het GTK wordt geïmplementeerd. Deze is gelijk aan “v1”.
Voor instance-level interacties (bijvoorbeeld een FHIR-read of een FHIR-update) dient het <app-id> van de GBZ-applicatie die fungeert als Resource Server te worden toegevoegd aan de base-URL. Voor FHIR-search interacties mag een <app-id> ook worden toegevoegd, maar is het niet verplicht. Een <app-id> die wordt gebruikt in de base-URL dient overeen te komen met het app-id dat is opgenomen in de audience van het gebruikte AORTA access_token.
Geretourneerde 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. 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 foutresponse en gaat verder met de exit stap van de main flow. |
AOF.UCe.VAL.200.v1 - Toetsing tokens bij inkomend request | Uitkomst | |
---|---|---|
Stap | Omschrijving | |
i | Het systeem controleert of alle vereiste tokens zijn toegevoegd aan het request | Ontbrekend token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow. | ||
ii | Het systeem controleert de geldigheid van de meegezonden, van toepassing zijnde, tokens
| Ongeldig token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow. |
AOF.UCe.VAL.150.v2 - Inhoudelijke toetsing request | Uitkomst | |
---|---|---|
Stap | Omschrijving | |
i | Het systeem toetst of het request geen malafide inhoud bevat (zie FHIR security, input validation). | Ongeldig FHIR-verzoek statuscode 400 Bad Request
|
Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow. | ||
ii | Het systeem bepaalt, m.b.v. de interactietabel en m.b.v. de _vrb_ter_scope claim in het AORTA access_token, welk interactie-id van toepassing is op het ontvangen request. Zie ook de toelichting "Bepalen van het interactie-id". | Ongeldig FHIR-verzoek statuscode 400 Bad Request
|
Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow. | ||
iii | Het systeem toetst of het verzoek voldoet aan de interface specificatie. Hierbij moet ook worden voldaan aan de toelichting "Controle van batch en transaction requests". FHIR-requests dienen te worden getoetst tegen de core FHIR specificaties en, indien van toepassing, tegen het FHIR-profiel dat van toepassing is voor het gevonden interactie-id. | Ongeldig FHIR-verzoek statuscode 400 Bad Request
|
Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow. |
AOF.UCe.VAL.300.v1 - Toetsing scope van request | Uitkomst | |
---|---|---|
Stap | Omschrijving | |
i | Het systeem controleert of het ontvangen resource request is toegestaan binnen de scope van het access_token. Zie ook de toelichting "Controle of request binnen scope valt" en de toelichting "Controle van batch en transaction requests". | Scope is niet toereikend statuscode 403 Forbidden
|
Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow. |
Stap | Omschrijving | Uitkomst |
---|---|---|
1 | Het systeem
| |
2 | Het systeem ontvangt een response. |
AOF.UCe.SCR.100.v1 - Screening van response | Uitkomst | |
---|---|---|
Stap | Omschrijving | |
i | Het systeem toetst of eventueel aanwezige BSN's uit het opgeleverde resultaat overeenkomen met het BSN dat is opgenomen in de | BSN in resultaat komt niet overeen met access_token statuscode 500 Internal Server Error
|
Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow. | ||
ii | Indien de response moet worden geretourneerd aan MedMij, dan verwijderd het systeem alle aanwezige BSN's uit de op te leveren response. | |
iii | Het systeem voert de filtering uit zoals beschreven in de toelichting "Filtering HTTP-response". |
Stap | Omschrijving | Uitkomst |
---|---|---|
3 <exit> | Het systeem retourneert een response naar de primaire actor. | Verwerking succesvol statuscode 200 OK |
AOF.UCe.VAL.100.v1 - Toetsing type content | Uitkomst | |
---|---|---|
Stap | Omschrijving | |
i | Het systeem ontvangt een verzoek en start de verwerking. 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 foutresponse en gaat verder met de exit stap van de main flow. |
AOF.UCe.VAL.250.v1 - Toetsing van een intern RB-request | Uitkomst | |
---|---|---|
Stap | Omschrijving | |
i | Het systeem controleert of alle vereiste tokens zijn toegevoegd aan het request | Ontbrekend token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow. | ||
ii | Het systeem controleert de geldigheid van de meegezonden, van toepassing zijnde, tokens
NB. wanneer het verzoek via een intern netwerk wordt ontvangen, en van een component van VZVZ, dan hoeft deze toets niet te worden uitgevoerd. | Ongeldig token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow. | ||
iii | Indien van toepassing: Het systeem controleert de samenhang tussen het AORTA access_token en het DigiD authenticatietoken, zoals omschreven in de de sectie "Toetsing van samenhang tussen tokens". NB. wanneer het verzoek via een intern netwerk wordt ontvangen, en van een component van VZVZ, dan hoeft deze toets niet te worden uitgevoerd. | Ongeldig token statuscode 401 Unauthorized
|
Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow. |
Stap | Omschrijving | Uitkomst |
---|---|---|
1 | Bij ontvangst van get-aorta-data request: Het systeem achterhaald, m.b.v. de AORTA Token Interface (middels een AORTA Token Request), welke interactie(s) moet(en) worden geïnitieerd, en bij welke GBx-applicatie(s). | Interactie(s) en/of GBx-applicaties kunnen niet worden vastgesteld statuscode 500 Internal Server Error |
Het systeem genereert de vereiste foutresponse en gaat verder met de exit stap van de main flow. | ||
Géén GBx-applicatie gevonden Het systeem gaat direct naar stap 5 (samenstellen van response) van de main flow. | ||
2 | Voor elke GBx-applicatie, waar één of meerdere interacties moeten worden geïnitieerd, worden voor iedere te initieren interactie de volgende stappen doorlopen:
| Ongeldige adressering Het systeem voegt een OperationOutcome toe (issue.severity=”warning”, issue.code "processing") met daarin informatie over de reden en gaat verder met de volgende interactie of GBx-applicatie. In geval van foutieve informatie in het request of token wordt geretourneerd: statuscode 400 Bad Request In geval van een interne fout in het systeem wordt geretourneerd: statuscode 500 Internal Server Error |
Transformatie niet geslaagd statuscode 500 Internal Server Error | ||
Het systeem genereert de vereiste foutresponse en gaat verder met de volgende interactie of GBx-applicatie. | ||
Interactie kon niet worden geïnitieerd Het systeem voegt een OperationOutcome toe (issue.severity=”warning”, issue.code "processing") met daarin informatie over de reden en gaat verder met de volgende interactie of GBx-applicatie. In geval van foutieve informatie in het request of token wordt geretourneerd: statuscode 400 Bad Request In geval van een interne fout in het systeem wordt geretourneerd: statuscode 500 Internal Server Error | ||
3 | Voor elke ontvangen response worden de volgende stappen doorlopen:
Indien geen (tijdige) response wordt ontvangen, dan worden bovenstaand stappen niet doorlopen en genereert het systeem zelfstandig de vereiste foutresponse. | Malafide inhoud Het systeem logt de gebeurtenis, negeert de betreffende response en gaat verder met de volgende interactie of GBx-applicatie. |
Geen (tijdig) antwoord van GBx-applicatie statuscode 504 Gateway Timeout | ||
Transformatie niet geslaagd statuscode 500 Internal Server Error | ||
Het systeem genereert de vereiste foutresponse en gaat verder met de volgende interactie of GBx-applicatie. | ||
4 | Het systeem consolideert alle ontvangen responses, zoals omschreven in de toelichting "Consolideren van de responses naar één FHIR-result" of, wanneer één v3-response moet worden opgeleverd, in AORTA documentatie voor v3-uitwisseling. | |
5 | Bij opleveren van een FHIR-result: het systeem overschrijft eventuele URL's in het opgeleverde resultaat
De juiste Resource Broker XXX-in wordt bepaald o.b.v. de inhoud van de vrb_client_id claim in het AORTA access_token. De base URL die hierbij hoort wordt verkregen uit het AORTA Stelseltoken. | |
6 <exit> | Het systeem retourneert een response naar de primaire actor. | Zie de toelichting "Consolideren van de responses naar één FHIR-result". |
Verwerking succesvol statuscode 200 OK
Voor bovenstaande criteria geldt dat ze
Wanneer een feitelijk, door Resource Server, geretourneerde statuscode moet worden toegevoegd aan een response, dan wordt dit gedaan in een OperationOutcome met:
| ||
Verwerking succesvol - resource instance gecreëerd statuscode 201 Created |