Versiegeschiedenis

Versie	Datum	Status	Wijzigingen
0.1.0	19 Dec 2022	concept	Delete response code aangepast

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

Ontwikkelaars hebben behoefte aan zoveel mogelijk gedetailleerde informatie bij HTTP-foutmeldingen om zo snel mogelijk de oorzaak van de foutmelding te kunnen achterhalen, Eindgebruikers daarentegen dienen zo beknopt mogelijke informatie bij een foutmelding te krijgen daar deze informatie ook interessant kan zijn voor mogelijke hackers.

Dit onderwerp is voor Koppeltaal verder uitgewerkt en enkele (extra) richtlijnen zijn hierbij aangeven op basis van praktische ervaring en bestaande oplossingen (zie o.a. https://www.hl7.org/fhir/http.html#Status-Codes en https://nl.wikipedia.org/wiki/Lijst_van_HTTP-statuscodes).

De filosofie die wordt toegepast bij koppeltaal is dat er enkel in het geval van geslaagde authenticatie en autorisatie een inhoudelijke melding over de resources wordt gegeven. In dat geval is het de bedoeling specifiek en breedsprakig te zijn over de details van de fout. In het geval van autorisatiefouten is het juist de bedoeling spaarzaam met details te zijn, om zo eventueel misbruik van de informatie te minimaliseren.

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. De uitputtende lijst van mogelijke codes met hun betekenis staat in de tabel bij het onderdeel http status codes. Het wordt van de FHIR resource service verwacht dat deze van deze codes gebruik maakt. De FHIR resource service heeft uit deze lijst van 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.

Foute Accept Header: 400 of 415.

Een onbekende waarde in de accept header kan met twee verschillende http status codes worden aangegeven. Een 415, Media-type niet ondersteund wordt typisch gegeven als er het MIME-Type in de header wel herkend wordt, maar niet wordt ondersteund, bijvoorbeeld application/pdf. De 400, Onjuiste aanvraag wordt gegeven als de MIME-Type helemaal niet wordt herkend, dus bijvoorbeeld application/vnd.lotus-wordpro. Of een MIME-Type wordt herkend als zodanig hangt af van de implementatie van de MIME-Types in de FHIR resource service.

If-Match header probleem: 409 of 412

Een If-Match header die niet overeenkomt met de verwachtte waarde duidt op een FHIR resource die in de tussentijd is aangepast. In deze situatie moet de client van de FHIR API op de hoogte gesteld worden van het feit dat de aanpassing die deze op de FHIR resource probeert uit te voeren op een verouderde versie van de resource gebeurt. Afhankelijk van die implementatie van de locking van de FHIR resource service kunnen er twee codes worden verzonden in dit geval. Maakt de FHIR resource service gebruik van pessimistisch locking; geeft deze een code 409 terug, maakt de FHIR resource service gebruik van optimistische locking, geeft deze een 412 terug.

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. Bij de implementatie gelden de volgende afwegingen.

Dezelfde fout kan bij verschillende FHIR resource services verschillende foutcodes teruggeven, het is dus sterk af te raden van specifieke codes afhankelijk te zijn. In plaats daarvan is het af

Toepassing en restricties

De FHIR API status codes

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.

Hoe met fouten om te gaan bij een FHIR RESTful interactie en welke HTTP-statuscode retourneert men.

Een belangrijk onderwerp bij de FHIR RESTful en Web-API discussie is het doorgeven van een status als reactie op een aanroep en een eventuele foutafhandeling bij een aanroep. Welke statuscode moet worden gegeven in reactie op een interactie en hoe moeten de HTTP-statuscodes worden gebruikt. Statuscodes met betrekking tot authenticatie, autorisatie, verificatie en omleidingen mogen niet worden geïnterpreteerd om de locatie van de bron zelf te wijzigen (een veelvoorkomende web programmeerfout).

De foutafhandeling moet informatie bevatten die geschikt is voor alle doelgroepen.

de eindgebruiker heeft een korte beschrijvend bericht nodig;
de applicatie ontwikkelaar heeft gedetailleerde informatie nodig om de applicatie te kunnen debuggen;
de applicatie gebruiker heeft een foutcode (HTTP-statuscode) nodig voor eventuele foutherstelacties en
de ondersteuning heeft gedetailleerde informatie en/of trefwoorden nodig uit de berichten of interactie, waarop ondersteuning kan worden gegeven

Geen stack-traces

Het kan soms verleidelijk zijn om een stack-trace op te nemen voor eenvoudige ondersteuning, wanneer er iets misgaat. Doe dit niet! Dit soort informatie is waardevol voor hackers en moet vermeden worden.

Gebruik (altijd bestaande) HTTP-statuscodes op een correct manier

De HTTP-standaard biedt meer dan 70 statuscodes om de return waarden te beschrijven. We hebben ze niet allemaal nodig. Gebruik HTTP-statuscodes en probeer ze netjes aan relevante standaardcodes toe te wijzen. De meeste REST API-providers gebruiken een kleine subset.

retourneer NIET alleen de HTTP-statuscode 200 (OK), ongeacht of het succesvol dan wel een fout betreft
gebruik de range 2xx, wanneer een aanvraag (volledig) verwerkt en geslaagd is.
gebruik de range 3xx, wanneer de client aanvullende acties moet ondernemen (omleiding) om een bepaalde aanvraag te voltooien. De vereiste actie kan worden uitgevoerd zonder interactie met de gebruiker, als het tweede verzoek een GET of HEAD is.
gebruik de range 4xx, wanneer de aanvraag niet (volledig) slaagt en de client deze aanvraag kan laten slagen door de aanvraag aan de client kant aan te laten passen.
gebruik de range 5xx, wanneer de aanvraag niet (volledig) slaagt door een interne foutmelding aan de server kant

HTTP Status codes

Informele berichten.

Dit zijn geen fouten maar geven informatie over de aanvraag en beginnen met 2xx (goed gevolg) of 3xx (omleiding) . De FHIR resource service kan de volgende codes gebruiken zoals deze bij situatie past. Meerdere mogelijkheden zijn hierbij correct.

200 – OK. De aanvraag is verwerkt en geslaagd en de response van de payload is niet leeg (gebruikt met GET-, PUT- en POST-verzoeken)
201 – Nieuwe gegevens zijn aangemaakt en gepersisteerd (gebruikt met POST-verzoeken of PUT-verzoeken waar nieuwe gegevens zijn aangemaakt)
202 – Geaccepteerd. Als de verwijderde aanvraag is geaccepteerd, zonder aanvullende informatie over de uitkomst
204 – Geen inhoud – De gegevens zijn succesvol aangepast of verwijderd. Geen payload in de response (gebruikt met PUT- en DELETE-verzoeken).
301 – Verplaatst - De locatie van de gegevens zijn permanent verplaatst naar een andere locatie
304 – Niet gewijzigd – de klant kan gebruik maken van cache data met de If-Modified-Since of If-Nonen-Match HTTP headers
307 – Tijdelijk verplaatst - De locatie van de gegevens zijn tijdelijk verplaatst naar een andere locatie

Functionele fouten.

Dit zijn fouten die optreden als gevolg van het niet kunnen uitvoeren van een functionele vereiste. Deze fouten moeten worden beschreven als onderdeel van het functionele ontwerp van het systeem. Kies voor functionele fouten zorgvuldig een HTTP 4xx-code die past bij een bepaalde foutcondities.

400 – Onjuiste aanvraag - Het verzoek was ongeldig of kan niet worden uitgevoerd. De exacte fout moet worden uitgelegd in de payload content, zie OperationOutcome resource. Bijv. "diagnostics": "veld% param1% is niet geldig" (Validatie fouten).
401 – Onbevoegd - Het verzoek vereist een gebruikers authenticatie
403 – Verboden - De server heeft het verzoek begrepen, maar weigert het of de toegang is niet toegestaan.
404 – Niet gevonden - Er zijn geen gegevens aanwezig bij de aangegeven URI.
405 – Methode niet toegestaan. Gegevens bestonden niet voor de aanpassing en de aangegeven identificatie van de client mag niet voor de interactie gebruikt worden
406 - Aanvraag niet geaccepteerd. De aanvraag voldoet niet aan het formaat dat door de server ondersteunt wordt
409 - Conflict op wijzigingsverzoek. De server heeft de bron gelockt waardoor wijziging niet mogelijk is. Ook wel pessimistische locking genoemd.
410 – Weg - De gegevens zijn niet langer beschikbaar op de oorspronkelijke server en dat deze toestand waarschijnlijk permanent is
412 - Pre-conditie faalt. Als de versie-id in de If-Match niet overeenkomt. Ook wel optimistiche locking genoemd. Deze melding kan bij bij (FHIR) REST API PUT/PATCH/DELETE-verzoeken voorkomen.
415 – Media-type niet ondersteund, de FHIR resource service MAG deze status gebruiken bij een Accept of Content-Type header waarvan de waarde niet voorkomt in het onderdeel MIME-Types van FHIR REST API Foutafhandeling.
422 – Aanvraag kan niet verwerkt worden - De aangeboden gegevens voldoen niet aan bepaalde FHIR profielen of server bedrijfsregels
429 - Te veel aanvragen. Kans op een DDoS aanval of de aanvraag kan niet afgehandeld worden door bepaalde systeem limieten

Technische fouten.

Dit zijn run-time fouten die optreden als gevolg van het niet kunnen uitvoeren van bepaalde processen, query’s, methoden, enz. Ze hoeven geen onderdeel te zijn van het functionele ontwerp van het systeem. In een technisch interface document of API (Application Programming Interface) moeten de technische fouten in detail beschreven staan.

De cliënt kan niks wijzigen om zijn aanvraag te laten slagen. Als een 5xx-fout optreedt, moet de stack-trace worden vastgelegd bij de server en niet als response geretourneerd worden.

500 – Interne serverfout, Dit kunnen technische of connectie problemen zijn met het backend systeem.
501 – Server heeft de HEAD aanvraag niet geïmplementeerd. HEAD is hetzelfde als GET, maar dan zonder body in de response.
503 – Dienst niet beschikbaar. De aangeboden dienst kan in onderhoud zijn.

Autorisatie fouten.

Bij autorisatie fouten moet de dienstverlener (server) zo min mogelijk informatie weggeven. Het retourneren van te veel informatie kan details over de toegang blootleggen die NIET naar clients gecommuniceerd mogen worden.

Bijvoorbeeld de toegang tot het systeem wordt geweigerd omdat de vereiste verificatie ontbreekt of omdat de gebruiker NIET is geautoriseerd om toegang te krijgen of NIET toegang krijgt tot specifieke gegevens of om andere beleidsredenen.

Om de bruikbaarheid van de response af te wegen tegen de juiste hoeveelheid (detail) informatie te openbaren aan de client, moeten we dit met een bepaald beleid doordacht doorvoeren.

Typische status codes die veel gebruikt worden binnen FHIR zijn:

Bij alle beschermde HTTP requests:

Geautoriseerd?	Geauthentiseerd?	HTTP Statuscode
x	x	401 Unauthorized
x	√	403 Forbidden

Daarna is de status code afhankelijk van de HTTP method:

Actie	Beschrijving	Resource state	HTTP Statuscode
GET /Resource	Read all van type <Resource>	Nul of meer resources bestaan	200 OK
GET /Resource/<id>	Read van één resource	Resource bestaat	200 OK
GET /Resource/<id>	Read van één resource	Resource bestaat NIET	404 Not Found
GET /Resource/<id>	Read van één resource	Resource is soft-deleted	410 Gone
POST /Resource	Aanmaken van een resource	Resource is valide	201 Created
POST /Resource	Aanmaken van een resource	Resource is NIET valide	422 Unprocessable Entity
PUT /Resource/<id>	Updaten van een resource	Resource is valide, bestaat en `If-Match` header bevat de laatste versie	200 OK
PUT /Resource/<id>	Updaten van een resource	Resource is NIET valide	422 Unprocessable Entity
PUT /Resource/<id>	Updaten van een resource	Resource bestaat NIET	404 Not Found
PUT /Resource/<id>	Updaten van een resource	Resource is valide, bestaat en `If-Match` header bevat NIET de laatste versie	412 Precondition Failed
DELETE /Resource	Deleten van een resource	Resource bestaat	200 (met OperationOutcome)
DELETE /Resource	Deleten van een resource	Resource bestaat NIET	404 Not Found

Het idee van bovenstaande regels is dat eerst wordt bepaald of de aanroeper (principal) gerechtigd (geautoriseerd) is voor een (FHIR) resource.

Is het antwoord ‘nee’ of kan dat niet worden bepaald, bijvoorbeeld omdat de (FHIR) resource nodig is om deze beslissing te kunnen nemen en de resource niet bestaat, dan wordt 403 "Forbidden" teruggegeven.

Op deze manier wordt geen informatie teruggegeven over het al dan niet bestaan van een (FHIR) resource aan een niet-geautoriseerde principal.
Een bijkomend voordeel van de strategie om eerst te bepalen of er toegang is, biedt meer ruimte om de toegangscontrole (volledig) te scheiden van de business code.

Context en beschrijving (als het geen autorisatie fouten betreft) .

Als dit niet gedaan wordt, kost het veel ondersteuning: als de applicatie ontwikkelaars niet kunnen achterhalen waarom een aanvraag fout is gegaan, zullen ze hulp zoeken - en uiteindelijk zullen anderen tijd moeten besteden aan het opsporen van fouten.

Als het een validatiefout is, neem dan op waarom het is mislukt, waar het is mislukt en welk deel ervan is mislukt. Een bericht als "400 – Ongeldige invoer" is een onduidelijke foutmelding, waardoor kostbare ontwikkeltijd wordt verspild. Wees beschrijvend en voeg context toe: "Kan postcode niet plaatsen: het veld 'postalCode' moet het volgende patroon hebben \ d {4} [A-Z] {2}' (kreeg AB2A 23)".

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

De clients moeten onderscheid maken tussen HTTP-statuscodes die een fout aangeven en de statuscodes die een probleem op applicatieniveau aangeven.

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)

OperationOutcome

{
   "resourceType": "OperationOutcome",
   "issue": [
       {
           "severity": "error",
           "code": "processing",
           "diagnostics": "Invalid request: The FHIR endpoint on this server does not know how to handle GET operation[Patient] with parameters [[wrong_parameter]]",
           "expression": ["Patient.identifier[2].value"]
       }
   ]
}

Links naar gerelateerde onderwerpen

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

Oude tekst (kan op termijn wag)

Beschrijving

Hoe met fouten om te gaan bij een FHIR RESTful interactie en welke HTTP-statuscode retourneert men.

Een belangrijk onderwerp bij de FHIR RESTful en Web-API discussie is het doorgeven van een status als reactie op een aanroep en een eventuele foutafhandeling bij een aanroep. Welke statuscode moet worden gegeven in reactie op een interactie en hoe moeten de HTTP-statuscodes worden gebruikt. Statuscodes met betrekking tot authenticatie, autorisatie, verificatie en omleidingen mogen niet worden geïnterpreteerd om de locatie van de bron zelf te wijzigen (een veelvoorkomende web programmeerfout).

Bovenstaande onderwerp is voor Koppeltaal verder uitgewerkt en enkele (extra) richtlijnen zijn hierbij aangeven op basis van praktische ervaring en bestaande oplossingen (zie o.a. https://www.hl7.org/fhir/http.html#Status-Codes en https://nl.wikipedia.org/wiki/Lijst_van_HTTP-statuscodes).

De foutafhandeling moet informatie bevatten die geschikt is voor alle doelgroepen.

de eindgebruiker heeft een korte beschrijvend bericht nodig;
de applicatie ontwikkelaar heeft gedetailleerde informatie nodig om de applicatie te kunnen debuggen;
de applicatie gebruiker heeft een foutcode (HTTP-statuscode) nodig voor eventuele foutherstelacties en
de ondersteuning heeft gedetailleerde informatie en/of trefwoorden nodig uit de berichten of interactie, waarop ondersteuning kan worden gegeven

Voeg geen stack-traces toe

Het kan soms verleidelijk zijn om een stack-trace op te nemen voor eenvoudige ondersteuning, wanneer er iets misgaat. Doe dit niet! Dit soort informatie is waardevol voor hackers en moet vermeden worden.

Gebruik (altijd bestaande) HTTP-statuscodes op een correct manier

De HTTP-standaard biedt meer dan 70 statuscodes om de return waarden te beschrijven. We hebben ze niet allemaal nodig. Gebruik HTTP-statuscodes en probeer ze netjes aan relevante standaardcodes toe te wijzen. De meeste REST API-providers gebruiken een kleine subset. Zie: https://www.hl7.org/fhir/http.html#Status-Codes

retourneer NIET alleen de HTTP-statuscode 200 (OK), ongeacht of het succesvol dan wel een fout betreft
gebruik de range 2xx, wanneer een aanvraag (volledig) verwerkt en geslaagd is.
gebruik de range 3xx, wanneer de client aanvullende acties moet ondernemen (omleiding) om een bepaalde aanvraag te voltooien. De vereiste actie kan worden uitgevoerd zonder interactie met de gebruiker, als het tweede verzoek een GET of HEAD is.
gebruik de range 4xx, wanneer de aanvraag niet (volledig) slaagt en de client deze aanvraag kan laten slagen door de aanvraag aan de client kant aan te laten passen.
gebruik de range 5xx, wanneer de aanvraag niet (volledig) slaagt door een interne foutmelding aan de server kant

Informele berichten.

Dit zijn geen fouten maar geven informatie over de aanvraag en beginnen met 2xx (goed gevolg) of 3xx (omleiding) . Voorbeeld:

200 – OK. De aanvraag is verwerkt en geslaagd en de response van de payload is niet leeg (gebruikt met GET- en POST-verzoeken)
201 – Nieuwe gegevens zijn aangemaakt en gepersisteerd (gebruikt met POST-verzoeken)
202 – Geaccepteerd. Als de verwijderde aanvraag is geaccepteerd, zonder aanvullende informatie over de uitkomst
204 – Geen inhoud – De gegevens zijn succesvol aangepast of verwijderd. Geen payload in de response (gebruikt met PUT- en DELETE-verzoeken).
301 – Verplaats - De locatie van de gegevens zijn permanent verplaatst naar een andere locatie
304 – Niet gewijzigd – de klant kan gebruik maken van cache data met de If-Modified-Since of If-Nonen-Match HTTP headers
307 – Tijdelijk verplaatst - De locatie van de gegevens zijn tijdelijk verplaatst naar een andere locatie

Functionele fouten.

Dit zijn fouten die optreden als gevolg van het niet kunnen uitvoeren van een functionele vereiste. Deze fouten moeten worden beschreven als onderdeel van het functionele ontwerp van het systeem. Kies voor functionele fouten zorgvuldig een HTTP 4xx-code die past bij een bepaalde foutcondities.

400 – Onjuiste aanvraag - Het verzoek was ongeldig of kan niet worden uitgevoerd. De exacte fout moet worden uitgelegd in de payload content, zie OperationOutcome resource. Bijv. "diagnostics": "veld% param1% is niet geldig" (Validatie fouten).
401 – Onbevoegd - Het verzoek vereist een gebruikers authenticatie
403 – Verboden - De server heeft het verzoek begrepen, maar weigert het of de toegang is niet toegestaan.
404 – Niet gevonden - Er zijn geen gegevens aanwezig bij de aangegeven URI.
405 – Methode niet toegestaan. Gegevens bestonden niet voor de aanpassing en de aangegeven identificatie van de client mag niet voor de interactie gebruikt worden
406 - Aanvraag niet geaccepteerd. De aanvraag voldoet niet aan het formaat dat door de server ondersteunt wordt
409 - Conflict op wijzigingsverzoek. De server heeft de bron gelockt waardoor wijziging niet mogelijk is. Ook wel pessimistische locking genoemd.
410 – Weg - De gegevens zijn niet langer beschikbaar op de oorspronkelijke server en dat deze toestand waarschijnlijk permanent is
412 - Pre-conditie faalt. Als de versie-id in de If-Match niet overeenkomt. Ook wel optimistiche locking genoemd. Deze melding kan bij bij (FHIR) REST API PUT/PATCH/DELETE-verzoeken voorkomen.
415 – Media-type niet ondersteund
422 – Aanvraag kan niet verwerkt worden - De aangeboden gegevens voldoen niet aan bepaalde FHIR profielen of server bedrijfsregels
429 - Te veel aanvragen. Kans op een DDS aanval of de aanvraag kan niet afgehandeld worden door bepaalde systeem limieten

Technische fouten.

Dit zijn run-time fouten die optreden als gevolg van het niet kunnen uitvoeren van bepaalde processen, query’s, methoden, enz. Ze hoeven geen onderdeel te zijn van het functionele ontwerp van het systeem. In een technisch interface document of API (Application Programming Interface) moeten de technische fouten in detail beschreven staan.

De cliënt kant kan niks wijzigen om zijn aanvraag te laten slagen. Als een 5xx-fout optreedt, moet de stack-trace worden vastgelegd bij de server en niet als response geretourneerd worden.

500 – Interne serverfout, Dit kunnen technische of connectie problemen zijn met het backend systeem.
501 – Server heeft de HEAD aanvraag niet geïmplementeerd. HEAD is hetzelfde als GET, maar dan zonder body.
503 – Dienst niet beschikbaar. De aangeboden dienst kan in onderhoud zijn.

Autorisatie fouten.

Bij autorisatie fouten moet de dienstverlener (server) zo min mogelijk informatie weggeven. Het retourneren van te veel informatie kan details over de toegang blootleggen die NIET naar clients gecommuniceerd mogen worden.

Bijvoorbeeld de toegang tot het systeem wordt geweigerd omdat de vereiste verificatie ontbreekt of omdat de gebruiker NIET is geautoriseerd om toegang te krijgen of NIET toegang krijgt tot specifieke gegevens of om andere beleidsredenen.

Om de bruikbaarheid van de response af te wegen tegen de juiste hoeveelheid (detail) informatie te openbaren aan de client, moeten we dit met een bepaald beleid doordacht doorvoeren.

Typische methoden die veel gebruikt worden, zijn:

Bestaat de FHIR Resource?	Kan autorisatie bepaalt worden?	Geautoriseerd?	HTTP Statuscode
√	√	√	20x (200 OK)
√	√	x	401 Unauthorized
√	x	?	403 Forbidden
x	√	√	404 Not Found
x	√	x	403 Forbidden
x	x	?	403 Forbidden

Het idee van bovenstaande regels is dat eerst wordt bepaald of de aanroeper (principal) gerechtigd (geautoriseerd) is voor een (FHIR) resource.

Is het antwoord ‘nee’ of kan dat niet worden bepaald, bijvoorbeeld omdat de (FHIR) resource nodig is om deze beslissing te kunnen nemen en de resource niet bestaat, dan wordt 403 "Forbidden" teruggegeven.

Op deze manier wordt geen informatie teruggegeven over het al dan niet bestaan van een (FHIR) resource aan een niet-geautoriseerde principal.
Een bijkomend voordeel van de strategie om eerst te bepalen of er toegang is, biedt meer ruimte om de toegangscontrole (volledig) te scheiden van de business code.

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

Neem zoveel mogelijk context op in uw berichten en wees beschrijvend (als het geen autorisatie fouten betreft) .

Als dit niet gedaan wordt, kost het veel ondersteuning: als de applicatie ontwikkelaars niet kunnen achterhalen waarom een aanvraag fout is gegaan, zullen ze hulp zoeken - en uiteindelijk zullen anderen tijd moeten besteden aan het opsporen van fouten.

Als het een validatiefout is, neem dan op waarom het is mislukt, waar het is mislukt en welk deel ervan is mislukt. Een bericht als "400 – Ongeldige invoer" is een onduidelijke foutmelding, waardoor kostbare ontwikkeltijd wordt verspild. Wees beschrijvend en voeg context toe: "Kan postcode niet plaatsen: het veld 'postalCode' moet het volgende patroon hebben '\ d {4} [A-Z] {2}' (kreeg AB2A 23)".

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

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)

OperationOutcome

{
   "resourceType": "OperationOutcome",
   "issue": [
       {
           "severity": "error",
           "code": "processing",
           "diagnostics": "Invalid request: The FHIR endpoint on this server does not know how to handle GET operation[Patient] with parameters [[wrong_parameter]]",
           "expression": ["Patient.identifier[2].value"]
       }
   ]
}

De clients moeten onderscheid maken tussen HTTP-statuscodes die een fout aangeven en de statuscodes die een probleem op applicatieniveau aangeven.

Beschrijving

Overwegingen

Informatief vs. beveiliging

Meerdere status codes zijn goed

Toepassing en restricties

Hoe met fouten om te gaan bij een FHIR RESTful interactie en welke HTTP-statuscode retourneert men.

De foutafhandeling moet informatie bevatten die geschikt is voor alle doelgroepen.

Geen stack-traces

Gebruik (altijd bestaande) HTTP-statuscodes op een correct manier

HTTP Status codes

Informele berichten.

Functionele fouten.

Technische fouten.

Autorisatie fouten.

Bij alle beschermde HTTP requests:

Daarna is de status code afhankelijk van de HTTP method:

Context en beschrijving (als het geen autorisatie fouten betreft) .

Eisen

Voorbeelden

Links naar gerelateerde onderwerpen

Oude tekst (kan op termijn wag)

Beschrijving

Hoe met fouten om te gaan bij een FHIR RESTful interactie en welke HTTP-statuscode retourneert men.

De foutafhandeling moet informatie bevatten die geschikt is voor alle doelgroepen.

Voeg geen stack-traces toe

Gebruik (altijd bestaande) HTTP-statuscodes op een correct manier

Informele berichten.

Functionele fouten.

Technische fouten.

Autorisatie fouten.

Neem zoveel mogelijk context op in uw berichten en wees beschrijvend (als het geen autorisatie fouten betreft) .

Rationale

Implicaties

Voorbeelden

Toepassingsgebied

Onderbouwen

Eisen

Referenties

FHIR REST API Foutafhandeling

Beschrijving

Overwegingen

Informatief vs. beveiliging

Meerdere status codes zijn goed

Toepassing en restricties

Hoe met fouten om te gaan bij een FHIR RESTful interactie en welke HTTP-statuscode retourneert men.

De foutafhandeling moet informatie bevatten die geschikt is voor alle doelgroepen.

Geen stack-traces

Gebruik (altijd bestaande) HTTP-statuscodes op een correct manier

HTTP Status codes

Informele berichten.

Functionele fouten.

Technische fouten.

Autorisatie fouten.

Bij alle beschermde HTTP requests:

Daarna is de status code afhankelijk van de HTTP method:

Context en beschrijving (als het geen autorisatie fouten betreft) .

Eisen

Voorbeelden

Links naar gerelateerde onderwerpen

Oude tekst (kan op termijn wag)

Beschrijving

Hoe met fouten om te gaan bij een FHIR RESTful interactie en welke HTTP-statuscode retourneert men.

De foutafhandeling moet informatie bevatten die geschikt is voor alle doelgroepen.

Voeg geen stack-traces toe

Gebruik (altijd bestaande) HTTP-statuscodes op een correct manier

Informele berichten.

Functionele fouten.

Technische fouten.

Autorisatie fouten.

Neem zoveel mogelijk context op in uw berichten en wees beschrijvend (als het geen autorisatie fouten betreft) .

Rationale

Implicaties

Voorbeelden

Toepassingsgebied

Onderbouwen

Eisen

Referenties