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

Good practice: gebruik een GUID van 36 karakters
Voorbeeld: e842fd8c-34ce-44ee-aa80-bd2e2749457e

In het antwoord geeft MAGDA u dezelfde waarde terug in deze header

x-magda-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 richtlijn was op zich gebaseerd op deze standaard: https://tools.ietf.org/html/rfc7807

Het instance element zal ingevuld worden indien de errormessage wordt aangemaakt in de MAGDA business dienst. Dit kan getriggerd zijn door een response van de bron of door een unhappy flow in de MAGDA business dienst. Indien het instance element ontbreekt is de errorMessage aangemaakt door de APImanager. Dit kan bijvoorbeeld voorkomen bij het gebruik van een foute URL door de afnemer waarbij de API manager een 404 “Resource not found” terug geeft. In,dien de bron een 404 terug geeft aan MAGDA zal er wel een instance element aanwezig zijn.

OpenAPI definitie in YAML

  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". \
            \ MAGDA does not fill in this element. 
        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: An identifier for 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

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:

fout in autorisatie
technische fouten
functionele validatie
timeout naar de bron toe

Bron

Elke uitzondering (ruime zin), door de bron aangemaakt:

functionele uitzonderingen/fouten
technische fouten

Of X-Magda-Exceptions al dan niet gebruikt worden binnen een dienst wordt op de dienstspecifieke pagina's beschreven.

Index

MAGDA Gebruikersomgeving

Werking en overzicht uitzonderingen MAGDA RESTful services