Interfaces Common

HTTP-request

Gebruik

Deze interface is slechts bedoeld voor gebruik door VZVZ-componenten, en kan niet (rechtstreeks) worden gebruikt door GBx-applicaties.

Deze interface is slechts bedoeld voor gebruik door Mitz, en kan niet worden gebruikt door GBx-applicaties.

Deze interface is slechts bedoeld voor gebruik door Twinn GTK’s, en kan niet (rechtstreeks) worden gebruikt door GBx-applicaties.

HTTP headers

HTTP headers die zijn gedefinieerd in deze sectie worden opgenomen in de interfaces, waarin ze van toepassing zijn.

Alle interacties

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

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 FHIR interacties

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

AORTA-JSON interacties

Content-Type: application/json; charset=utf-8

Autorisatie Server interacties

Content-Type: application/x-www-form-urlencoded

Generieke FHIR parameters

Parameters die zijn gedefinieerd in deze sectie worden opgenomen in de interfaces, waarin ze van toepassing zijn.

Het gewenste formaat (JSON of XML) kan op de gebruikelijke manier via de Accept Header opgegeven worden, maar kunnen ook via de FHIR _format parameter doorgegeven worden. 

Ondersteunde waarden voor de _format parameter zijn voor alle interacties, waar van toepassing:

• de mogelijke opties die duiden op het FHIR JSON formaat of op het FHIR XML formaat.

Indien beide (Accept header en _format parameter) in een request voorkomen, geldt de waarde van de _format parameter. Indien geen enkele voorkomt, dan geldt het formaat van het Content-Type.

HTTP-response

HTTP headers

HTTP headers die zijn gedefinieerd in deze sectie worden opgenomen in de interfaces, waarin ze van toepassing zijn.

AORTA FHIR interacties

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.

AORTA-JSON interacties

Content-Type: application/json; charset=utf-8

Response codes

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

Algemeen

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

Succes

statuscode 200 OK

Succes FHIR

statuscode 200 OK

• Wanneer een geldige FHIR zoekparameter wordt ontvangen die niet wordt ondersteund, dan wordt een OperationOutcome met issue.code "not supported" opgenomen in het resultaat. 

• Wanneer een ongeldige FHIR zoekparameter wordt ontvangen, dan wordt een OperationOutcome met issue.code "invalid" en de van toepassing zijnde issue.details geretourneerd opgenomen in het resultaat.

• Wanneer een FHIR zoekparameter een geldige waarde bevat die niet wordt ondersteund, dan wordt een OperationOutcome met issue.code "not supported" en de van toepassing zijnde issue.details geretourneerd.

• Wanneer een optionele FHIR zoekparameter een ongeldige waarde heeft, dan wordt een OperationOutcome met issue.code "value" en de van toepassing zijnde issue.details geretourneerd.

Voor bovenstaande criteria geldt dat ze

• voor FHIR-interacties die worden vertaald van naar HL7v3: worden getoetst in de resource broker;

• voor FHIR-interacties die niet worden vertaald: worden getoetst in de resource server.

Succes FHIR-create

statuscode 201 Created

Resource Broker Succes

statuscode 200 OK

• 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

statuscode 400 Bad Request

Ongeldig FHIR-verzoek

statuscode 400 Bad Request

• Wanneer een verplichte FHIR zoekparameter ontbreekt, dan wordt een OperationOutcome met issue.code "required" en de van toepassing zijnde issue.details geretourneerd.

• Wanneer een verplichte FHIR zoekparameter een ongeldige waarde heeft, d.w.z. een waarde die niet is gespecificeerd binnen de gegevensdienst, dan wordt een OperationOutcome met issue.code "value" 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. Indien de WWW-Authenticate HTTP response header wordt geproduceerd door de resource broker, dan wordt een realm attribuut met waarde "aorta" toegevoegd.

Ongeldig OAuth-verzoek

statuscode 400 Bad Request, error=invalid_request

Verplicht token ontbreekt

statuscode 401 Unauthorized

• In deze situatie wordt geen nadere informatie over de opgetreden fout geretourneerd. In deze situatie wordt, conform RFC 6750, ook een WWW-Authenticate HTTP response header met als auth-scheme "Bearer", maar zonder foutcode of nadere informatie omtrent de fout geretourneerd. Indien de WWW-Authenticate HTTP response header wordt geproduceerd door de resource broker, dan wordt een realm attribuut met waarde "aorta" toegevoegd.

Ongeldig token

statuscode 401 Unauthorized

• 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. Indien de WWW-Authenticate HTTP response header wordt geproduceerd door de resource broker, dan wordt een realm attribuut met waarde "aorta" toegevoegd.

• In deze situatie mag daarnaast ook een OperationOutcome met issue.code "security" worden geretourneerd.

statuscode 401 Unauthorized

Request mag niet worden verwerkt

statuscode 403 Forbidden

• In deze situatie wordt geen nadere informatie over de opgetreden fout geretourneerd.

Onjuiste autorisatie

statuscode 403 Forbidden

• 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 de WWW-Authenticate HTTP response header wordt geproduceerd door de resource broker, dan wordt een realm attribuut met waarde "aorta" toegevoegd.

• 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 Forbidden

• 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. Indien de WWW-Authenticate HTTP response header wordt geproduceerd door de resource broker, dan wordt een realm attribuut met waarde "aorta" toegevoegd.

• In deze situatie wordt een OperationOutcome met issue.code "suppressed" geretourneerd.

Scope niet toereikend

statuscode 403 Forbidden

• 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. Indien de WWW-Authenticate HTTP response header wordt geproduceerd door de resource broker, dan wordt een realm attribuut met waarde "aorta" toegevoegd.

• In deze situatie mag daarnaast ook een OperationOutcome met issue.code "forbidden" of "security" worden geretourneerd.

Client niet geautoriseerd OAuth

statuscode 403 Forbidden, error=access_denied, error_description="Initiërende applicatie beschikt niet over de vereiste capabilities."

Destination wil interactie niet ontvangen via Twiin

statuscode 403 Forbidden, error=access_denied, error_description="AORTA-deelnemer kan/wil interactie niet ontvangen via Twiin."

Object niet gevonden

statuscode 404 Not Found

Request niet ondersteund

statuscode 404 Not Found

• 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 Not Found

• In deze situatie wordt een OperationOutcome met issue.code "not-found" en de van toepassing zijnde issue.details geretourneerd.

Geen match bij conditional-delete

statuscode 200 OK

• In deze situatie wordt een OperationOutcome met issue.severity “warning“, issue.code "not-found" en de van toepassing zijnde issue.details geretourneerd, in dit geval “SEARCH_NONE”.

Gevraagd type content niet ondersteund

statuscode 406 Not Acceptable

Meerdere overeenkomsten

statuscode 412

• In deze situatie wordt een OperationOutcome met issue.code "multiple-matches" en de van toepassing zijnde issue.details geretourneerd.

Gehanteerd type content niet ondersteund

statuscode 415 Unsupported Media Type

Entity kan niet worden verwerkt

statuscode 422 Unprocessable Entity

• In deze situatie wordt een OperationOutcome met issue.code "search-none" en de van toepassing zijnde issue.details geretourneerd.

Teveel verzoeken

statuscode 429 Too Many Requests

Fout in server

statuscode 500 Internal Server Error

Fout in achterliggende server

statuscode 500 Internal Server Error

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

Server kan request (tijdelijk) niet verwerken

statuscode 503 Service Unavailable

Server ontving geen tijdig antwoord van achterliggend systeem

statuscode 504 Gateway Timeout