...
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.
| Info | ||
|---|---|---|
| ||
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 |
| Info | ||
|---|---|---|
| ||
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.
...
- 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.
...
- 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
| Anchor | ||||
|---|---|---|---|---|
|
Informele berichten.
Dit zijn geen fouten maar geven informatie over de aanvraag en beginnen met 2xx (goed gevolg) of 3xx (omleiding) . Voorbeeld: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
...
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.
...
- 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.
...
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.
...