| Insert excerpt | ||||||
|---|---|---|---|---|---|---|
|
Opbouw interface
Elke MAGDA 2.0 webservice is op eenzelfde manier opgebouwd, zowel voor het Verzoek als voor Repliek en zelfs Uitzonderingen. Dit is het MAGDA 2.0 canoniek model. Dit maakt het voor de afnemer eenvoudiger MAGDA -diensten te implementeren.
Verzoek
Het request bericht bevat steeds een <Verzoek> element dat bestaat uit 2 elementen:
<Context>
<Vragen>
Het <Vragen> element bevat een <Vraag> element met op zijn beurt 2 onderliggende elementen:
<Referte>
<Inhoud>
Op deze pagina
| Table of Contents |
|---|
Verbonden pagina’s
| Child pages (Children Display) | ||
|---|---|---|
|
Context
Het Context element dat structureel identiek is voor de verschillende MAGDA diensten zal in eerste instantie voor autorisatie doeleinden aangewend worden, en in tweede instantie om Request en Reponse ketting te kunnen correleren. Afhankelijk van de afnemer en de dienst die men wenst op te roepen, moet de Context op een verschillende wijze ingevuld worden.
Element Context/ | Cardinaliteit | Omschrijving | ||||||
|---|---|---|---|---|---|---|---|---|
Naam | Verplicht | Bevat de naam van de dienst die wordt aangevraagd of waarvoor er een antwoord beschikbaar is. De naam in dit element wordt gevalideerd tegenover de “geprogrammeerde” naam. De dienstnaam is terug te vinden in de dienstspecifieke documentatie. Vb: Persoon.GeefPersoon, Onderneming.GeefOnderneming, … | ||||||
Versie | Verplicht | Bevat het versienummer van de dienst die wordt aangevraagd. Het opgegeven versienummer moet overeenkomen met de “geprogrammeerde” versie. De versie is terug te vinden in de dienstspecifieke documentatie. Formaat: <Hoofdnummer>.<Bijnummer>.<Buildnummer> Vb: 02.00.0000 | ||||||
Bericht | ||||||||
Type | Verplicht | het bericht type moet "VRAAG" zijn. Functioneel wordt er gevalideerd dat er voor een vraag/antwoord wel degelijk VRAAG opgegeven wordt en niet ANTWOORD of DATAGRAM. | ||||||
Tijdstip | Verplicht | Dit is het tijdstip (datum en uur) waarop de boodschap overhandigd werd aan/door MAGDA. Er wordt geen functionele validatie uitgevoerd op de datum en het tijdstip, wel een technische en dit op de vorm van de datum en het tijdstip. | ||||||
Datum | Formaat: yyyy-mm-dd | |||||||
Tijd | Formaat: HH:mm:ss.sss | |||||||
Afzender | ||||||||
Identificatie | Verplicht | Bevat de URI van de afnemer. Deze moet overeenkomen met de URI gekoppeld aan de dienst/versie in de MAGDA administratiedatabank (VIPADM). Komt het niet overeen met de configuratie in VIPADM wordt er een Uitzondering aangemaakt.
| ||||||
Naam | Optioneel | Bevat de naam van de afzender. De afnemer is vrij een naam te kiezen. | ||||||
Referte | Verplicht | Bevat een waarde die elke boodschap uniek identificeert. Geprefereerd wordt met een UUID van 36 lang gewerkt. | ||||||
OrganisatieEenheid | Optioneel | De OrganisatieEenheid of “Instrumenterende Overheid” is een niveau van toepassingscategorisatie. Het is immers mogelijk dat meerdere organisatie-eenheden eenzelfde toepassing gebruiken op een MAGDA dienst te benaderen. Op dit moment wordt dit niet gebruikt binnen MAGDA. | ||||||
Hoedanigheid | Verplicht/optioneel | De hoedanigheid bepaalt in welk kader - met welke reden - de dienst bevraagd wordt.
| ||||||
Gebruiker | Optioneel | Mag niet aanwezig zijn in de Vraag. | ||||||
Ontvanger | Optioneel | Optioneel element. Mag integraal weggelaten worden in de request. | ||||||
Identificatie | Verplicht | Indien het Ontvanger element wordt ningevuld moet volgens de MAGDA richtlijnen dit steeds “vip.vlaanderen.be” zijn. | ||||||
Naam | Optioneel | Optioneel element. Mag weggelaten worden | ||||||
Referte | Optioneel | Niet opgeven in het verzoek. | ||||||
OrganisatieEenheid | Optioneel | Niet opgeven in het verzoek. | ||||||
Hoedanigheid | Optioneel | Niet opgeven in het verzoek. | ||||||
Gebruiker | Optioneel | Niet opgeven in het verzoek. | ||||||
Annotaties | Optioneel | Niet opgeven in het verzoek. | ||||||
| Expand | ||||||
|---|---|---|---|---|---|---|
| ||||||
|
Vragen
| Info |
|---|
Voor een MAGDA 2.0 webservice is maar één Vraag-element toegelaten. |
Element | Cardinaliteit | Omschrijving | |||
|---|---|---|---|---|---|
Vraag | |||||
Referte | Verplicht | Een unieke referte per vraag. Geprefereerd is dit een UUID van 36 lang. Daar een webservice oproep maar één Vraag-element toelaat, is het toegestaan dat de vraagreferte identiek is aan de referte opgegeven in in Afzender/Referte. | |||
Inhoud | Verplicht | De feitelijk vraag van de webservice. Dit kan ook een registratie zijn, of verwijdering van gegevens, ... .
| |||
Repliek
Een webservice kan twee soorten antwoorden teruggeven:
of een SOAPFault.
of een Repliek (al dan niet met Uitzonderingen).
Voor meer informatie rond de foutafhandeling van een MAGDA 2.0 webservice wordt verwezen naar Werking en overzicht uitzonderingen MAGDA 2.0 Webservices.
Enkel de Repliek wordt op deze pagina besproken.
Ontvangt de afnemer een Repliek dan zal de opbouw van een XML als volgt er uit zien:
| Info |
|---|
Het Antwoorden-element zal nooit samen voorkomen met een Uitzondering op het niveau van Repliek. Verwar het Uitzonderingen-element op Repliek niet met het Uitzonderingen-element binnen het Antwoord-element. Voor meer informatie rond de foutafhandeling binnen MAGDA 2.0 webservices wordt verwezen naar volgende pagina: Werking en overzicht uitzonderingen MAGDA 2.0 Webservices. |
Repliek/Context
De Context bij een Repliek zal op een volgende manier opgebouwd worden:
Element Context/ | Omschrijving | ||
Naam | Naam van de dienst Vb Persoon.GeefPersoon | ||
Versie | Versie van de dienst Vb 02.00.0000 | ||
Bericht |
| ||
Type | “ANTWOORD” | ||
Tijdstip | Datum en tijdstip van aanmaak antwoord | ||
Afzender | Opmerkingen uit Analyse space toevoegen | ||
Identificatie | vaste waarde “vip.vlaanderen.be” | ||
Naam | vaste waarde “MagdaGateway“ | ||
Referte | Dit is de MAGDA VIPDialoogcode, een unieke code binnen MAGDA ter identificatie van elke request - response flow. Deze is onder de vorm van een UUID, 36 lang. | ||
OrganisatieEenheid | Zal niet aanwezig zijn | ||
Hoedanigheid | Zal niet aanwezig zijn | ||
Gebruiker | Zal niet aanwezig zijn | ||
Ontvanger | |||
Identificatie | Zoals doorgestuurd in Afzender/Identificatie in de vraag | ||
Naam | Zoals doorgestuurd in Afzender/Identificatie in de vraag | ||
Referte | Zoals doorgestuurd in Afzender/Identificatie in de vraag. Zo kunnen het vraag- en antwoordbericht aan elkaar gelinkt worden indien dit element voor elek vraag uniek is. | ||
OrganisatieEenheid | Zal niet aanwezig zijn | ||
Hoedanigheid | Zoals doorgestuurd in Afzender/Identificatie in de vraag | ||
Gebruiker | Zal niet aanwezig zijn | ||
Annotaties | Wordt standaard niet ingevuld. Indien dit gebruikt wordt, zal dit expliciet vermeld worden in de handleiding van de dienst. | ||
Repliek/Antwoorden
Na verwerking wordt een <Antwoorden><Antwoord>-element aangemaakt met hierin
Het Referte-element
Een Inhoud- en/of Uitzonderingen-element
Het Referte-element is de waarde van het Vraag/Referte-element zoals doorgestuurd in de request. Op deze manier kunnen vraag en antwoord aan elkaar gelinkt worden. Of al dan niet een Inhoud en/of Uitzondering-element aangemaakt wordt is afhankelijk van de verwerking.
Een Inhoud-element wordt gezet indien de verwerking succesvol verlopen is. Er zijn bijvoorbeeld
Gegevens gevonden op basis van de sleutel;
Gegevens gevonden op basis van verschillende zoekcriteria;
Of de registratie van gegevens is geslaagd.
Het Inhoud-element bevat voornamelijk de gegevens die gevraagd werden, denk maar aan de Persoon, of een (LED)Bewijs. Bij een registratie kan die ook een Resultaat-element bevatten die de status van verwerking aangeeft. Het Inhoud-element is dienstspecifiek: Handleidingen dienstenaanbod .
Een Uitzondering-element (kan in combinatie met een Inhoud-element) indien een fout heeft plaatsgevonden, dit kan een functionele, businessfout zijn of een waarschuwing.
Functionele fouten zijn bijvoorbeeld:
Ongeldig INSZ
Ongeldig ondernemingsnummer
Niet bestaande postcode
…. .
Onder businessfouten wordt specifieke businesslogica bedoeld die gevalideerd moet worden, voor of tijdens de verwerking van de gegevens. Ook deze businesslogica kan een uitzondering aanmaken. Veel businessfouten zijn vertalingen van fouten die door de bron worden teruggegeven; zij zijn tenslotte de houders van de meeste businesslogica.
Al deze fouten resulteren in een Uitzondering (of meerdere) op niveau 3, dus onder Antwoord. Voor meer informatie met betrekking tot de werking van Uitzonderingen wordt verwezen naar Werking en overzicht uitzonderingen MAGDA 2.0 Webservices.
Repliek/Uitzonderingen
De uitzonderingen op dit niveau hebben veelal betrekking op autorisatiefouten. Voor meer informatie rond de Uitzonderingen op Repliek van een MAGDA 2.0 webservice wordt verwezen naar Werking en overzicht uitzonderingen MAGDA 2.0 Webservices.