Beschrijving

Bij de interactie met de FHIR REST API kunnen er op verschillende niveaus fouten ontstaan. Er kunnen zich problemen voordoen met de authenticatie, de autorisatie, met de input of met de status of beschikbaarheid van de resource. In al deze situaties moet de client van de FHIR REST API op de juiste manier geïnformeerd worden over de fout. 

Overwegingen

Informatief vs. beveiliging

Over het algemeen geldt dat meer informatie in een foutmelding altijd beter is. In koppeltaal zien we dit niet anders. Echter, er is hier een belangrijke uitzondering op: en dat zijn de meldingen rondom beveiliging en/of het ontbreken van de juiste credentials. De (fout) meldingen van koppeltaal FHIR API zijn daarop in te delen in twee groepen; een groep van alles wat zich voordoet met een aanvraag (request) die niet geautoriseerd is en een groep van alle meldingen van een aanvraag (request) die wel geautoriseerd is. Om te voorkomen dat er informatie van de server en de gegeven wordt vrijgegeven aan onbevoegden geldt dat voor de eerste groep de meldingen minimaal en summier zijn. Voor de tweede groep, dus voor geautoriseerde aanvragen (requests), zijn de meldingen juist zo gedetailleerd en uitgebreid mogelijk. 

Meerdere status codes zijn goed

De FHIR API definieert de HTTP status codes die voor de verschillende aanvragen door de API client verwacht kunnen worden. Het wordt van de FHIR resource service verwacht dat deze van deze codes gebruik maakt. De FHIR resource service heeft uit de lijst van toegestane codes de keuze, het is de bedoeling de code die het meest van toepassing is te gebruiken. Dit heeft als gevolg dat het voorkomt dat, voor dezelfde fout bij verschillende FHIR resource services andere foutcodes worden gegeven. We leggend dit uit met een aantal voorbeelden.

...

Als client van de FHIR API is het af te raden afhankelijk te zijn van specifieke error codes. Het is dan ook sterk af te raden code of tests te schrijven die van specifieke status codes afhankelijk zijn, eenvoudigweg omdat deze per FHIR resource service implementatie of configuratie kunnen verschillen.

Toepassing en restricties

De FHIR API

De FHIR resource service implementeert de FHIR API en volgt zoveel mogelijk de HTTP status codes zoals in deze API worden vastgelegd. Primair verwijzen we naar de documentatie van FHIR API. Een overzicht van welke status codes kunnen voorkomen wordt in onderdeel 3.1.0.17 van de FHIR API documentatie uiteengezet.

Binnen koppeltaal maken we duidelijk onderscheid tussen de type fouten die kunnen voorkomen. In het geval van autorisatie fouten moet de FHIR resource service terughoudend zijn met het geven van informatie. In de meldingen van fouten die zich voordoen na de autorisatie kan de FHIR service uitgebreider zijn in de meldingen.

Code ranges

De FHIR api geeft in het response een status code mee. Deze status codes staan niet vast, de FHIR resource service mag tot bepaalde hoogte zelf bepalen welke code in welke situatie van toepassing is. Het is dan ook te adviseren de status code van het antwoord van de FHIR resource service op range niveau te checken, de uitzondering hierop zijn de 401 en 403 status codes. De volgende ranges zijn van toepassing:

• 2xx: De 200 range kan worden beschouwd als een succesvolle status code. De FHIR resource service kan in bepaalde situaties een 201 terugsturen als een nieuwe entiteit is aangemaakt.
• 3xx: De 300 range zal niet direct van de FHIR resource service verwacht worden. In een infrastructuur kan het voorkomen dat een 301 of 302 gebruikt wordt na verhuizingen of om verkeer naar een https endpoint te upgraden.
• 4xx: deze range komen fouten voor waarvan de oorzaak bij de aanvrager ligt. De 401 en 403 codes worden gebruikt voor de autorisatie- en authenticatiefouten en liggen vast. Hoe en wanneer de andere fouten kunnen voorkomen hangt sterk af van de actie die wordt ondernomen.
• 5xx: deze range zou bij normaal gebruik en een stabiele FHIR resource service niet mogen voorkomen. Deze fouten hebben betrekking op de onverwachte fouten die in de FHIR resource service of de omliggende infrastructuur voorkomen.

Autorisatie fouten.

Bij autorisatie fouten moet de dienstverlener (server) zo min mogelijk informatie weggeven. Er valt onderscheid te maken tussen twee aspecten die invloed hebben op het verlenen van toegang:

...

Overige fouten en status codes

De tabel hieronder geeft een niet uitputtend overzicht van de status codes (groen) en foutcodes (rood). Sommige rijen hebben meerdere status codes, omdat in dat geval meerdere status codes goed zijn. Deze tabel geeft een informatief overzicht en is niet normatief.

De OperationOutcome resource

FHIR definieert een OperationOutcome resource die gebruikt kan worden om specifieke gedetailleerde verwerkbare (fout) informatie over te brengen. De OperationOutcome kan worden geretourneerd met elke HTTP 4xx- of 5xx-reactie, maar dit is niet vereist - veel van deze fouten kunnen worden gegenereerd door een generieke server dat ten grondslag ligt aan een FHIR resource service.

Het is de bedoeling om, met uitzondering van de 401 en 403 status codes, de operation outcome zo informatief mogelijk te maken. Zo is het behulpzaam om bij validatiefouten zoveel mogelijk detail van het validatieprobleem mee te geven. 

Eisen

ERR - Eisen (en aanbevelingen) voor foutafhandeling

Voorbeelden

De OperationOutcome resource bevat minimaal de volgende velden, beginnend met minimaal 1 issue en een severity die het type response aangeeft: fatal (fataal), error (fout) , warning (waarschuwing) of information (informatie)

...

Links naar gerelateerde onderwerpen

Anchor
links_status_codes links_status_codes

Links over status codes 

Aanvullende informatie over het gebruik van HTTP Statuscodes in REST APIs is te vinden op:

...