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 |
|---|---|---|---|
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 |
date | REQUEST / RESPONSE | NEEN | Hier kan u de timestamp mee geven.
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 |
x-magda-sender-id | REQUEST | NEEN | Dient enkel ingevuld te worden door Trusted Third Parties. Laat hen toe om mede te delen in naam van welke Afnemer de dienst opgeroepen wordt.
|
x-magda-sender-qualitycode | REQUEST | NEEN | Dient enkel ingevuld te worden door Trusted Third Parties. Laat hen toe om mede te delen in naam van welke Afnemer de dienst opgeroepen wordt.
|
x-magda-sender-organisationalunit | REQUEST | NEEN | Dient enkel ingevuld te worden door Trusted Third Parties. Laat hen toe om mede te delen in naam van welk departement (binnen de structuur van de Afnemer) de dienst opgeroepen wordt. Wordt enkel gebruikt om rapportering te drijven.
|
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.
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:
Oorsprong
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.
Op deze pagina
Verbonden pagina’s
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