| Panel |
|---|
Deze pagina beschrijft de generieke werking van de MAGDA RESTful webservices. Elke webservice werkt op het vlak van HTTP headers op eenzelfde manier. Ook de foutafhandeling zal steeds op dezelfde manier gebeuren. Foutafhandeling kan gebeuren op 2 niveaus, afhankelijk van de ernst van de fout. |
HTTP headers
Ziehier een overzicht van de HTTP headers die gebruikt worden in de communicaties met het MAGDA platform.
Header | Richting | VERPLICHT | Opmerking |
|---|---|---|---|
X-Correlation-Id | REQUEST / RESPONSE | JA | Deze ID identificeert de REQUEST. Hij is verplicht mee te geven en dient uniek te zijn over alle requests van een bepaalde afnemer
In het antwoord geeft MAGDA u dezelfde waarde terug in deze header |
X-Magda- |
Bevat een JSON datastructuur van sleutel - waarde paren. Zie onder voor meer info.
Hier kunnen gegevens in meegegeven worden die dienst specifiek zijn.
Indien ze van toepassing zijn voor de dienst, worden ze beschreven in de handleiding van de desbetreffende dienst
Exceptions | RESPONSE | NEEN | Bevat een JSON datastructuur die een eventuele fout beschrijft. Zie onder voor meer info. Deze worden enkel dienst specifiek gebruikt en gevuld – maar zullen steeds deze vorm hebben. Indien ze van toepassing zijn voor de dienst, worden ze beschreven in de handleiding van de desbetreffende dienst |
Foutafhandeling
Generieke foutcodes, welke hieronder zijn opgelijst, worden gegenereerd door het MAGDA platform zelf en zijn niet afhankelijk van dienst tot dienst. Meestal zijn dit authenticatie- of autorisatiefouten. Codes die aan een specifieke dienst verbonden zijn wordt gedocumenteerd bij de dienst zelf en worden dan afgehandeld op het niveau van de HTTP headers.
Code | Bericht | Opmerking |
|---|---|---|
400 | Bad Request | Wanneer de validatie van uw request faalt. Dit betekent dat uw request niet correct is. U zal de request moeten aanpassen. Het heeft geen zin om deze zelfde request opnieuw te proberen. |
401 | Unauthorized | Wanneer u geen toegang heeft tot deze dienst. Dit betekent dat uw request niet correct is of u niet de nodige toegangsrechten heeft om deze dienst te gebruiken. U zal de request moeten aanpassen. Het heeft geen zin om deze zelfde request opnieuw te proberen. |
500 | Internal Server Error | Wanneer er een onverwachte fout optreedt. U dient de MAGDA helpdesk te contacteren. Het heeft geen zin om deze zelfde request opnieuw te proberen. |
502 | Bad Gateway | Wanneer er fout optreedt in onze connectie naar de bron of wanneer onze bron een onverwachte fout terug geeft Het kan nuttig zijn om dezelfde request opnieuw te proberen (met inachtname van de nodige tussentijd). |
503 | Service Unavailable | Wanneer de dienst momenteel niet beschikbaar is. Het kan nuttig zijn om dezelfde request opnieuw te proberen (met inachtname van de nodige tussentijd). |
504 | Gateway Timeout | Wanneer de bron niet tijdig antwoord. Het kan nuttig zijn om dezelfde request opnieuw te proberen (met inachtname van de nodige tussentijd). |
Error Message Body
Elke fout die MAGDA terug geef wordt ook voorzien van een HTTP body. Die Die richtlijn was op zich gebaseerd op deze standaard: https://tools.ietf.org/html/rfc7807
Swagger definitie
| Code Block |
|---|
ErrorMessage:
required:
- detail
- title
type: object
properties:
type:
type: string
description: A URI reference that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
title:
type: string
description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation.
status:
type: string
description: The HTTP status code generated by the origin server for this occurrence of the problem.
detail:
type: string
description: A human-readable explanation specific to this occurrence of the problem.
instance:
type: string
description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
description: A representation of a generic error message |
Voorbeeld van een error message
| Code Block |
|---|
HTTP/1.1 400 Bad Request
{
"title": "Bad Request",
"detail": "[Path '/eboxDeliveryData/recipient/eboxType'] Instance value (\"CITIZENT\") not found in enum (possible values: [\"ENTERPRISE\",\"CITIZEN\"])",
"instance": "9f32f093-e5e8-40e0-89ca-fdaaf5635dae"
} |
X-Magda-Exceptions
De Magda uitzondering die in de header terug gegeven worden hebben steeds onderstaande structuur:
Identificatie
Elke fout die MAGDA terug geef wordt ook voorzien, numeriek, 5 lang. MAGDA streeft er naar foutcodes maximaal te hergebruiken over de diensten heen.
Type
Het type uitzondering duidt de zwaarte van uitzondering aan. Echter wordt aanbevolen enkel op de foutcode te werken.
Type | Definitie |
|---|---|
FOUT | De afnemer zal geen data object (Vb Persoon) ontvangen van de businessdienst doordat er een fout opgetreden is. Dit moet niet zozeer een technische fout zijn, maar kan ook een validatiefout zijn, autorisatiefout, … .. Vb: INSZ checksum is ongeldig, foutcode van de bron waarbij er geen data object terug komt, … |
INFORMATIE | De afnemer ontvangt een data object maar binnen de uitzondering is er extra informatie opgenomen met betrekking tot het data object of de verwerking. |
WAARSCHUWING | De afnemer ontvangt een data object, of zou er een kunnen ontvangen, maar moet actie ondernemen. Vb: Persoon heeft een nieuw INSZ verkregen |
Diagnose
De diagnose is de tekstuele omschrijving van de opgetreden fout.
Omstandigheid
De omstandigheid wordt enkel gebruikt voor de foutcode van de bron door te geven. Enkel de foutcode, geen omschrijving of andere bijkomende gegevens.
Oorsprong
De Oorsprong geeft aan wie de fout ontdekt heeft.
Daar foutcodes maximaal hergebruikt worden is de mogelijkheid dat een foutcode met een oorsprong MAGDA maar ook met een oorsprong bron kan voorkomen binnen een dienst.
Oorsprong | Richtlijn |
|---|---|
MAGDA | Elke uitzondering die door MAGDA zelf aangemaakt is:
|
Bron | Elke uitzondering (ruime zin), door de bron aangemaakt:
|
| Info |
|---|
Of X-Magda-Exceptions al dan niet gebruikt worden binnen een dienst wordt op de dienstspecifieke pagina's beschreven. |
X_Magda_Annotations
Binnen een Uitzonderingen kunnen Annotatie-elementen voorkomen. Deze Annotatie-elementen, onder de vorm van een naam/waarde-paar, geven meer informatie rond de uitzonderingen.
De meest voorkomende annotatie is Oud INSZ en Nieuw INSZ.
| Code Block | ||||
|---|---|---|---|---|
| ||||
<Annotaties>
<Annotatie>
<Naam>Oud INSZ</Naam>
<Waarde>69011005111</Waarde>
</Annotatie>
<Annotatie>
<Naam>Nieuw INSZ</Naam>
<Waarde>63032411222</Waarde>
</Annotatie>
</Annotaties> |
| Info |
|---|
Of X-Magda-Annotations al dan niet gebruikt worden binnen een dienst wordt op de dienstspecifieke pagina's beschreven. |
| Panel | ||
|---|---|---|
| ||
|