Page Comparison

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.

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).
• 304 – Niet gewijzigd – de klant kan gebruik maken van cache data met de If-Modified-Since of If-Nonen-Match HTTP headers 

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. Bijv. "veld% param1% is niet geldig" (Validatie fouten).
• 401 – Niet geautoriseerd - 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/412 – Conflict - Conflict met de huidige status van de bron (gebruikt met PUT-verzoeken)
• 415 – Media-type niet ondersteund
• 422 – Aanvraag kan niet verwerkt worden - De aangeboden gegevens voldoen niet aan bepaalde FHIR profielen of server bedrijfsregels

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.

In een productieomgeving is het wenselijk om voor het (kunnen) autoriseren zo min mogelijk informatie weg te geven.

...

Bestaat de FHIR Resource?

...

Kan autorisatie bepaalt worden?

...

Geautoriseerd?

...

HTTP Statuscode

...

Het idee van bovenstaande regels is dat eerst wordt bepaald of de aanroeper (principal) gerechtigd is voor een resource. Is het antwoord ‘nee’ of kan dat niet worden bepaald, bijvoorbeeld omdat de 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 resource aan een niet-geautoriseerde principal.
Een bijkomend voordeel van de strategie om eerst te bepalen of er toegang is, meer ruimte biedt om de toegangscontrole te scheiden van de business code.

Neem zoveel mogelijk context op in uw berichten en wees beschrijvend.

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)

{
   "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"]
       }
   ]
}

...