Interfaces Common - 0.7.x

Generieke eisen voor alle server-to-server interfaces

AOF.GS-I.GEN.100.v3

De volgende eisen gelden voor alle server-to-server interfaces:

HTTP-requests en -responses worden verzonden conform HTTP versie 1.1.
Tenzij anders vermeld in de specificatie van een interface, worden interfaces slechts aangeboden op AORTA-net, dus via een GZN.
Alle HTTP-verkeer wordt verzonden binnen een TLS verbinding, waarbij verplicht gebruik wordt gemaakt van tweezijdige server authenticatie. Uitzonderingen hierop zijn:
1. Op de AORTA CapabilityStatement Interface wordt slechts server authenticatie vereist, maar mag de resource server ook client authenticatie vereisen.
2. Op de AS Metadata Interface wordt slechts server authenticatie toegepast.
TLS clients en TLS servers dienen tenminste TLS versie 1.2 te ondersteunen en mogen hierbij slechts gebruik maken van een ciphersuite uit de categorie "Goed", zoals genoemd in bijlage C van de ICT-beveiligingsrichtlijnen voor Transport Layer Security (TLS).
TLS clients en TLS servers maken bij voorkeur echter gebruik van een hogere TLS versie.
Server authenticatie vindt plaats middels PKIo servercertificaten of, voor zorgaanbieders, m.b.v. UZI-servercertificaten.
Voor alle op FHIR gebaseerde interfaces gelden de generieke eisen uit de MedMij informatiestandaarden. Dit betekent ondermeer dat zowel JSON als XML moet worden ondersteund.
Een request dat wordt gericht aan een type server die is opgenomen in de lijst met server rollen van het AORTA Stelseltoken, mag slechts worden gericht aan een server die deze rol blijkens het AORTA Stelseltoken ook daadwerkelijk heeft. Het geldende AORTA Stelseltoken dient periodiek te worden opgehaald via de AORTA Stelsel Metadata Interface. De aangeven caching directives dienen hierbij te worden gevolgd. Voorbeelden:
1. Resource Broker VnC dient de base-URL van de Transformatie Server te verkrijgen via het AORTA Stelseltoken.
2. Bij controle van een AORTA access_token dient de issuer van het access_token te zijn opgenomen als een Autorisatie Server in het AORTA Stelseltoken.
3. Een Resource Client (xIS) dient de base-URL van Resource Broker ZA-in te verkrijgen via het AORTA Stelseltoken.

Mapping tussen OID en FHIR-based namingsystems

Onderstaande tabel bevat een mapping van de binnen AORTA on FHIR gehanteerde namingsystems.

OID	URI	Description
2.16.528.1.1007.3.1	http://fhir.nl/fhir/NamingSystem/uzi-nr-pers	Uniek Zorgverlener Identificatienummer Personen
2.16.528.1.1007.3.2	http://fhir.nl/fhir/NamingSystem/uzi-nr-sys	UZI nummer van systeem, gekoppeld aan UZI services certificaat
2.16.528.1.1007.3.3	http://fhir.nl/fhir/NamingSystem/ura	UZI-register abonneenummer
2.16.840.1.113883.2.4.3.11.8	http://fhir.nl/fhir/NamingSystem/aorta-rolcode	Zie: https://www.nictiz.nl/wp-content/uploads/OID-ovrzicht-150819.pdf
2.16.840.1.113883.2.4.3.11.25	-	Organisatie-id in het kader van AORTA.
2.16.840.1.113883.2.4.3.111.8	-	AORTA Component rollen
2.16.840.1.113883.2.4.3.111.15.1	http://fhir.nl/fhir/NamingSystem/aorta-contextcode	AORTA contextcode
2.16.840.1.113883.2.4.3.111.15.4	-	AORTA requestID
2.16.840.1.113883.2.4.6.1	http://fhir.nl/fhir/NamingSystem/agb-z	Vektis AGB-z zorgverlener tabel
2.16.840.1.113883.2.4.6.3	http://fhir.nl/fhir/NamingSystem/bsn	Burgerservicenummer
2.16.840.1.113883.2.4.6.6	http://fhir.nl/fhir/NamingSystem/aorta-app-id	Applicatie ID binnen de AORTA infrastructuur
2.16.840.1.113883.2.4.15.4	http://fhir.nl/fhir/NamingSystem/aorta-gegevenssoort	AORTA gegevenssoort
2.16.840.1.113883.2.4.15.111	http://fhir.nl/fhir/NamingSystem/uzi-rolcode	UZI rolcode
-	http://fhir.nl/fhir/NamingSystem/aorta-taskcode	Codesystem voor AORTA Task.code
-	http://fhir.nl/fhir/NamingSystem/medmij-scope	Scope attribuut, zoals gehanteerd in de MedMij authorization flow

HTTP-response

AOF.GS-I.HTR.100.v3

Wanneer een resource server een uitzondering/foutsituatie detecteert, dan dient het dit aan te geven in de HTTP-response. Een uitzondering kan op een aantal verschillende manieren worden gecommuniceerd, vaak ook middels een combinatie ervan:

De HTTP statuscode;
Een HTTP Authenticate response header;
Een FHIR OperationOutcome, met hierin ondermeer de volgende attributen
- issue.severity (verplicht), deze moet passend zijn voor de situatie en in lijn zijn met de geretourneerde HTTP statuscode;
- issue.code (verplicht);
- issue.details (optioneel in FHIR, maar indien aangegeven in onderstaande tabel verplicht te vullen conform de aangegeven valueset;
- issue.diagnostics (optioneel in FHIR, optioneel binnen AORTA, waarbij altijd de beveiliging van de resource server in ogenschouw moet worden genomen).

De resource server retourneert fouten conform https://informatiestandaarden.nictiz.nl/wiki/MedMij:V2020.01/FHIR_IG#Handling_errors en http://hl7.org/fhir/STU3/search.html#errors. De te retourneren HTTP statuscode en mee te sturen aanvullende informatie, is opgenomen in onderstaande tabel.

In de bijbehorende use cases is gespecificeerd welke situaties gedetecteerd dienen te worden. Niet alle situaties zijn van toepassing op iedere use case.

Gedetecteerde situatie	Response
Succes	statuscode 200
Resource broker success	statuscode 200 Wanneer één of meerdere van de achterliggende resource servers een fout heeft geretourneerd (anders dan het niet voldoen aan de MedMij beschikbaarheidsvoorwaarde), dan wordt voor ieder van deze resource servers een OperationOutcome toegevoegd met issue.severity "`warning`", issue.code "`processing`" en issue.diagnostics "`<de betreffende appID>`".
Ongeldig verzoek (de ontvangen interactie is ongeldig, voldoet niet aan de specificaties - deze situatie kan ook ontstaan doordat een verplichte header, niet zijnde een security token, ontbreekt of ongeldig is)	statuscode 400 Wanneer een verplichte FHIR zoekparameter ontbreekt, dan wordt een OperationOutcome met issue.code "`required`" en de van toepassing zijnde issue.details geretourneerd Wanneer een FHIR zoekparameter een ongeldige waarde heeft, dan wordt een OperationOutcome met issue.code "`value`" en de van toepassing zijnde issue.details geretourneerd; Bij ontvangst van een FHIR zoekparameter die niet is gespecificeerd binnen de gegevensdienst wordt een OperationOutcome met issue.code "`not-supported`" en de van toepassing zijnde issue.details geretourneerd. Wanneer een ontvangen FHIR resource instance ongeldig is, dan wordt een OperationOutcome met issue.code "`invalid`" en de van toepassing zijnde issue.details geretourneerd. In deze situatie wordt, indien van toepassing, conform RFC 6750, ook een WWW-Authenticate HTTP response header met als auth-scheme "Bearer" en een error attribuut met waarde "invalid_request" geretourneerd.
Ongeldige notificatie	statuscode 400
Een verplicht token ontbreekt	statuscode 401 In deze situatie wordt geen nadere informatie over de opgetreden fout geretourneerd.
Ongeldig token (een ontvangen token is niet geldig, of kan niet worden gevalideerd)	statuscode 401 In deze situatie wordt, conform RFC 6750, ook een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`invalid_token`" geretourneerd. In deze situatie mag daarnaast ook een OperationOutcome met issue.code "`security`" worden geretourneerd.
Request van deze client mag niet worden verwerkt, bijvoorbeeld "de PGO server komt niet voor op de MedMij whitelist".	statuscode 403 In deze situatie wordt geen nadere informatie over de opgetreden fout geretourneerd.
De client beschikt niet over de juiste autorisatie, bijvoorbeeld een xIS probeert een TKID te activeren voor een ander xIS. mismatch tussen BSN in AORTA access_token en BSN in ontvangen gegevens.	statuscode 403 Indien een `Authorization` header werd gebruikt in het request, dan wordt in deze situatie, conform RFC 6750, een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`access_denied`" geretourneerd. Indien het een FHIR-request betreft, dan wordt in deze situatie (ook) een OperationOutcome met issue.code "`forbidden`" geretourneerd.
Niet voldaan aan (MedMij) beschikbaarheidsvoorwaarde	statuscode 403 In deze situatie wordt, conform RFC 6750, een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`access_denied`" geretourneerd. In deze situatie wordt een OperationOutcome met issue.code "`suppressed`" geretourneerd.
Scope niet toereikend voor interactie	statuscode 403 In deze situatie wordt, conform RFC 6750, ook een `WWW-Authenticate` HTTP response header met als auth-scheme "`Bearer`" en een `error` attribuut met waarde "`insufficient_scope`" geretourneerd. In deze situatie mag daarnaast ook een OperationOutcome met issue.code "`forbidden`" of "`security`" worden geretourneerd.
FHIR resourcetype is niet gespecificeerd binnen de gegevensdienst, OF FHIR resourcetype of request type wordt niet ondersteund	statuscode 404 In deze situatie wordt een OperationOutcome met issue.code "`not-supported`" en de van toepassing zijnde issue.details geretourneerd.
resource-id niet bekend	statuscode 404 In deze situatie wordt een OperationOutcome met issue.code "`not-found`" en de van toepassing zijnde issue.details geretourneerd.
Gevraagde acceptVersion in de AORTA-Version header wordt niet ondersteund	statuscode 406
Gehanteerde contentVersion in de AORTA-Version header wordt niet ondersteund	statuscode 415
Fout in server	statuscode 500
Fout in achterliggende server	statuscode 500 In deze situatie wordt, voor iedere resource server die een fout produceerde, een OperationOutcome toegevoegd met issue.severity "`warning`", issue.code "`processing`" en issue.diagnostics "`<appID van betreffende resource server>`".
Fout in achterliggende Mitz-dienst	statuscode 500 In deze situatie wordt een OperationOutcome toegevoegd met issue.severity "`error`", issue.code "`transient`" en issue.diagnostics "Fout bij interactie met Mitz".