Document toolboxDocument toolbox


DIGITAAL VLAANDEREN

Overzicht Header parameters RESTful-services

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

Een overzicht van de HTTP headers die gebruikt worden in de communicaties met het MAGDA platform.

Header

Richting

VERPLICHT

Opmerking

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

date

REQUEST / RESPONSE

NEEN

Hier kan u de timestamp mee geven.

  • Voorbeeld: Fri, 17 Apr 2020 05:36:35 GMT

In het antwoord geeft MAGDA u de date terug waarop MAGDA het antwoord overhandigde

x-magda-annotations

REQUEST / RESPONSE

NEEN

Bevat een JSON datastructuur van sleutel - waarde paren. Zie onderaan 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

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

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.

Swagger definitie

ErrorMessage: type: "object" required: - "title" - "status" - "detail" 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"

x-magda-exceptions

De Magda uitzondering die in de header terug gegeven worden hebben steeds onderstaande structuur:

Elke fout die MAGDA terug geef wordt ook voorzien, numeriek, 5 lang. MAGDA streeft er naar foutcodes maximaal te hergebruiken over de diensten heen. 

Het type uitzondering duidt de zwaarte van uitzondering aan. Echter wordt aanbevolen enkel op de foutcode te werken.

Type

Definitie

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

De diagnose is de tekstuele omschrijving van de opgetreden fout.

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

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.

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.

<Annotaties> <Annotatie> <Naam>Oud INSZ</Naam> <Waarde>69011005111</Waarde> </Annotatie> <Annotatie> <Naam>Nieuw INSZ</Naam> <Waarde>63032411222</Waarde> </Annotatie> </Annotaties>

Of x-magda-annotations al dan niet gebruikt worden binnen een dienst wordt op de dienstspecifieke pagina's beschreven.


Voor vragen of opmerkingen kan u de MAGDA helpdesk contacteren

De MAGDA Gebruikersomgeving is een officiële website van de Vlaamse overheid

uitgegeven door Digitaal Vlaanderen