{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"20382b75-eabd-4e2d-a2ae-057d8c370452"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"3f0159ab-c10d-402f-9298-bea8a3d10612"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Over deze documentatie","type":"text"}]},{"type":"paragraph","content":[{"text":"In deze documentatie vindt u de algemene richtlijnen om REST API’s te bouwen die data aanleveren aan Mijn Burgerprofiel. Dit document bouwt verder op de bestaande richtlijnen van de ","type":"text"},{"text":"Expertise Groep Architectuur","type":"text","marks":[{"type":"link","attrs":{"href":"https://data.vlaanderen.be/doc/richtlijnen/iv-rest-api-richtlijnen/"}}]},{"text":": ","type":"text"},{"text":"https://data.vlaanderen.be/doc/richtlijnen/iv-rest-api-richtlijnen/","type":"text","marks":[{"type":"link","attrs":{"href":"https://data.vlaanderen.be/doc/richtlijnen/iv-rest-api-richtlijnen/"}}]},{"text":" ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Gerelateerde standaarden en richtlijnen","type":"text"}]},{"type":"paragraph","content":[{"text":"In deze documentatie wordt er verder gebouwd op de volgende standaarden en richtlijnen van de Vlaamse Overheid:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"De OSLO-standaarden (","type":"text"},{"text":"data.vlaanderen.be","type":"text","marks":[{"type":"link","attrs":{"href":"https://data.vlaanderen.be/doc/richtlijnen/iv-rest-api-richtlijnen/"}}]},{"text":") vormen de basis voor overheidsinformatie. Het is soms verplicht, maar altijd aanbevolen, om de data volgens deze afspraken te ontsluiten.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"De URI-standaard voor persistente identificatoren. Dit is een technische standaard om data via persistente identificatoren te ontsluiten.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"De OSLO Generieke Hypermedia driven API's, zie ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://github.com/Informatievlaanderen/generieke-hypermedia-api"}},{"text":". Hypermedia-driven (Hypermedia As The Engine Of Application State, kort HATEOAS) betekent dat de API zelf-documenterend is en geëxploreerd kan worden door machines. Deze standaard vult de afspraken aan voor specifieke topics.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"RFC 7807 Problem Details for HTTP API's: ","type":"text"},{"text":"https://tools.ietf.org/html/rfc7807","type":"text","marks":[{"type":"link","attrs":{"href":"https://tools.ietf.org/html/rfc7807"}}]}]}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Het is ","type":"text"},{"text":"sterk aanbevolen","type":"text","marks":[{"type":"strong"}]},{"text":" om deze standaarden en richtlijnen te kennen vóór verder te gaan met dit document.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"REST URL-vormrichtlijnen","type":"text"}]},{"type":"paragraph","content":[{"text":"Hiervoor worden de richtlijnen van de ","type":"text"},{"text":"Expertise Groep Architectuur","type":"text","marks":[{"type":"link","attrs":{"href":"https://data.vlaanderen.be/doc/richtlijnen/iv-rest-api-richtlijnen/#rest_url"}}]},{"text":" gevolgd.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Volg zeker de richtlijn m.b.t. het versioneren van de API's. Voeg een versienummer toe in de URL en gebruik hiervoor enkel natuurlijke getallen, bv ","type":"text"},{"text":"v1","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"v2","type":"text","marks":[{"type":"code"}]},{"text":", … ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Vermijd breaking changes binnen een versie. Zodra er breaking changes bestaan, moet er een volgende versie gereleased te worden.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Concreet ziet de basisstructuur van een URL er als volgt uit: ","type":"text"},{"text":"https://{hostname}/{version}/{resource}/{identifier}","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Een voorbeeld van een URL met parameters: ","type":"text"},{"text":"https://mbp.vlaanderen.be/v3/attesten/ac518dbc?taal=nl&nisCode=31005","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"API-designrichtlijnen","type":"text"}]},{"type":"paragraph","content":[{"text":"Hiervoor worden de richtlijnen van de ","type":"text"},{"text":"Expertise Groep Architectuur","type":"text","marks":[{"type":"link","attrs":{"href":"https://data.vlaanderen.be/doc/richtlijnen/iv-rest-api-richtlijnen/#rest_url"}}]},{"text":" gevolgd, met aandacht voor de volgende punten, waaraan er in dit document nog extra invulling gegeven wordt.","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"adba6a4c-5233-4be4-a3dc-4666429b330f"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[133.0]},"content":[{"type":"paragraph","content":[{"text":"Onderwerp","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[627.0]},"content":[{"type":"paragraph","content":[{"text":"Regel","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[133.0]},"content":[{"type":"paragraph","content":[{"text":"Datum & tijd","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[627.0]},"content":[{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"De datum- en tijdsnotatie volgen het ","type":"text"},{"text":"ISO8601-formaat","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Tijdstippen die deel uitmaken van een respons worden genormaliseerd teruggegeven als UTC met tijdzone-informatie.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"De volgende zijn correct:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Datum: ","type":"text"},{"text":"2016-01-25","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Datum & tijd met tijdzone indicatie:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"2016-01-25T21:34:55.451+00:00","type":"text","marks":[{"type":"code"}]},{"text":" of ","type":"text"},{"text":"2016-01-25T21:34:55.451Z","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"subsecondenaanduiding kan in 3 cijfers na de seconde, 6 cijfers na de seconde of 9 cijfers na de seconde","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"tot op de seconde kan ook: ","type":"text"},{"text":"2016-01-25T21:34:55Z","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"}]}]}]}]}]}]}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Formaten zonder tijdszone-indicatie worden ","type":"text"},{"text":"NIET","type":"text","marks":[{"type":"strong"}]},{"text":" geaccepteerd, bv: ","type":"text"},{"text":"2016-01-25T21:34:55","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[133.0]},"content":[{"type":"paragraph","content":[{"text":"Payload","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[627.0]},"content":[{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Het standaardformaat voor een respons is ","type":"text"},{"text":"JSON","type":"text","marks":[{"type":"strong"}]},{"text":". De structuur van deze JSON dient te voldoen aan RMM niveau 3 .","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Indien een object niet beschikbaar is en verplicht terug te geven is volgens het domein, heeft het de waarde ","type":"text"},{"text":"null","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Indien een lijst van objecten niet beschikbaar is en verplicht terug te geven is volgens het domein, wordt een l","type":"text"},{"text":"ege lijst","type":"text","marks":[{"type":"strong"}]},{"text":" verwacht.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Gebruik bij voorkeur ","type":"text"},{"text":"camelCase","type":"text","marks":[{"type":"strong"}]},{"text":" voor attributtnamen.","type":"text"}]}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[133.0]},"content":[{"type":"paragraph","content":[{"text":"HTTP-statuscodes","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[627.0]},"content":[{"type":"paragraph","content":[{"text":"Maak overwogen gebruik van HTTP Statuscodes en beperk waar mogelijk tot een subset.","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"Zie de ","type":"text"},{"text":"Expertise Groep Architectuur","type":"text","marks":[{"type":"link","attrs":{"href":"https://data.vlaanderen.be/doc/richtlijnen/iv-rest-api-richtlijnen/#api_design"}}]},{"text":" richtlijnen en ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://tools.ietf.org/html/rfc2616#section-9.5"}},{"text":" voor meer informatie.","type":"text"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[133.0]},"content":[{"type":"paragraph","content":[{"text":"Standaarderrorpayload","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[627.0]},"content":[{"type":"paragraph","content":[{"text":"Standaarderrors zijn het gevolg van technische, systeem- of softwareproblemen. Deze worden weergegeven met de overeenkomstige HTTP errorcode en een standaard error payload.","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"Een standaard error payload volgt de afspraken ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://tools.ietf.org/html/rfc7807"}},{"text":" . Zie het hoofdstuk ","type":"text"},{"text":"Foutboodschappen","type":"text","marks":[{"type":"link","attrs":{"href":"https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/2076934790/Algemene+REST+API-specificaties#Foutberichten"}}]},{"text":" voor meer informatie.","type":"text"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[133.0]},"content":[{"type":"paragraph","content":[{"text":"Validatie-error payload","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[627.0]},"content":[{"type":"paragraph","content":[{"text":"Validatie-errors zijn het gevolg van een ","type":"text"},{"text":"businessevaluatie","type":"text","marks":[{"type":"strong"}]},{"text":" van de payload meegegeven in voorafgaande API-interactie. Validatie-errors verhinderen mogelijks het verzetten van interactie met (onderdelen van) de API. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Er bestaat geen vaste correlatie tussen HTTP-errorcodes en het bestaan van validatie-errors. Het kan dus best voorkomen dat een HTTP-responscode 200 wordt ontvangen met validatie-errors. Bijvoorbeeld wanneer een draftobject wordt opgeslagen en al de validatie-errors hierbij worden teruggegeven. Het is aan de designer van de REST API om zo goed mogelijk de HTTP-responscode te laten overeenkomen met het bestaan van validatie-errors en hiermee de interactie van de API te sturen.","type":"text"}]},{"type":"paragraph","content":[{"text":"Validatie-errors worden meegegeven als een lijst met als naam ","type":"text"},{"text":"errors","type":"text","marks":[{"type":"code"}]},{"text":". De elementen van die lijst volgen de basisstructuur van de standaarderrors: ","type":"text"},{"text":"type","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code"}]},{"text":" en ","type":"text"},{"text":"detail","type":"text","marks":[{"type":"code"}]},{"text":" zijn verplicht in dit geval. Eigen uitbreidingen zijn toegestaan.","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"Zie het hoofdstuk ","type":"text"},{"text":"Foutboodschappen","type":"text","marks":[{"type":"link","attrs":{"href":"https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/2076934790/Algemene+REST+API-specificaties#Foutberichten"}}]},{"text":" voor meer informatie. ","type":"text"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[133.0]},"content":[{"type":"paragraph","content":[{"text":"HTTP Header","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[627.0]},"content":[{"type":"paragraph","content":[{"text":"Bebruik de standaard HTTP-headers - waar mogelijk - om het gebruik van de API te bevorderen.","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"Zie het hoofdstuk ","type":"text"},{"text":"Headers","type":"text","marks":[{"type":"link","attrs":{"href":"https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/2076934790/Algemene+REST+API-specificaties#Headers"}}]},{"text":" voor meer informatie over de specifieke headers die gebruikt en verwacht worden.","type":"text"}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[133.0]},"content":[{"type":"paragraph","content":[{"text":"CorrelatieID","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[627.0]},"content":[{"type":"paragraph","content":[{"text":"Om de verwerking van een API request te kunnen volgen is het zinvol om een correlatieID te initiëren door de proxy verbonden met de externe wereld. Deze correlatieID moet worden doorgegeven door elke verwerkende service naar zijn achterliggende API-oproepen. Op deze manier kan de verwerking van 1 externe request over verschillende API's heen gevolgd worden. Deze correlatieID zal worden opgeslagen in een HTTP header x-correlation-id.","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"Zie ","type":"text"},{"text":"CorrelatieId en RequestId ","type":"text","marks":[{"type":"link","attrs":{"href":"https://vlaamseoverheid.atlassian.net/wiki/spaces/IKPubliek/pages/2076934790/Algemene+REST+API-specificaties#CorrelationId-en-RequestId"}}]},{"text":"voor meer informatie.","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Collecties","type":"text"}]},{"type":"paragraph","content":[{"text":"Bij het opvragen van collecties wordt verwacht dat er paginering ondersteund wordt, ten minste op niveau van de API-structuur.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Paginering","type":"text"}]},{"type":"paragraph","content":[{"text":"In de URL worden er 2 query parameters ondersteund","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"limit","type":"text","marks":[{"type":"code"}]},{"text":": Aantal resultaten op 1 resultatenpagina (1-based)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"offset","type":"text","marks":[{"type":"code"}]},{"text":": Volgnummer van het eerstvolgend resultaat dat als eerste wordt verwacht (startend bij 0).","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Voorbeeld","type":"text","marks":[{"type":"strong"}]},{"text":" van 10 resultaten per pagina opvragen waarbij de eerste pagina wordt opgevraagd: ","type":"text"},{"text":"https://mbp.vlaanderen.be/v3/attesten?limit=10&offset=0","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"Voorbeeld","type":"text","marks":[{"type":"strong"}]},{"text":" van de tweede pagina die resultaten teruggeeft beginnend bij het 11de resultaat: ","type":"text"},{"text":"https://mbp.vlaanderen.be/v3/attesten?limit=10&offset=10","type":"text","marks":[{"type":"code"}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Het wordt sterk aangeraden om een bovengrens te hanteren voor de ","type":"text"},{"text":"limit","type":"text","marks":[{"type":"code"}]},{"text":" parameter. Als de client meer dan de bovengrens vraagt, geef dan slechts terug tot de bovengrens.","type":"text"}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Als er geen limit- en offsetparameters meekomen, gebruik dan defaultwaarden. Goede defaultwaarden zijn ","type":"text"},{"text":"offset=0","type":"text","marks":[{"type":"code"}]},{"text":" en een redelijke limiet zoals ","type":"text"},{"text":"limit=10","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Metadata","type":"text"}]},{"type":"paragraph","content":[{"text":"Bij gepagineerde data is het verplicht op metadata mee te sturen over de paginering. Doe dit door een ","type":"text"},{"text":"pagemetadata","type":"text","marks":[{"type":"code"}]},{"text":"-element toe te voegen aan het responselement:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"\"pageMetadata\": {\n \"offset\": 0,\n \"size\": 10,\n \"totalItems\": 50,\n}","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"offset","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"(verplicht)","type":"text","marks":[{"type":"strong"}]},{"text":" start van de offset op de teruggegeven pagina","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"size","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"(","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"verplicht","type":"text","marks":[{"type":"strong"}]},{"text":") ","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"het aantal objecten teruggegeven op deze pagina","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"totalItems","type":"text","marks":[{"type":"code"}]},{"text":" ","type":"text"},{"text":"(","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":"verplicht, indien gekend","type":"text","marks":[{"type":"strong"}]},{"text":")","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" het totaal aantal objecten in de gehele collectie - als het totaal aantal items niet gekend is, moet deze parameter niet teruggegeven worden","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Links","type":"text"}]},{"type":"paragraph","content":[{"text":"Bij het teruggeven van een collectie moeten er ook bepaalde links aanwezig zijn. De volgende zijn ","type":"text"},{"text":"verplicht","type":"text","marks":[{"type":"strong"}]},{"text":" bij het teruggeven van een collectie:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"self","type":"text","marks":[{"type":"code"}]},{"text":" de opgegeven ","type":"text"},{"text":"href","type":"text","marks":[{"type":"code"}]},{"text":" wijst naar de huidige pagina van de collectie.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"next","type":"text","marks":[{"type":"code"}]},{"text":" (","type":"text"},{"text":"alleen als er een volgende pagina is","type":"text","marks":[{"type":"strong"}]},{"text":") de opgegeven ","type":"text"},{"text":"href","type":"text","marks":[{"type":"code"}]},{"text":" wijst naar de volgende pagina van de collectie, alleen als er effectief een volgende pagina is","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"prev","type":"text","marks":[{"type":"code"}]},{"text":" (","type":"text"},{"text":"enkel er een vorige pagina is","type":"text","marks":[{"type":"strong"}]},{"text":") de opgegeven ","type":"text"},{"text":"href","type":"text","marks":[{"type":"code"}]},{"text":" wijst naar de vorige pagina van de collectie, alleen als er effectief een vorige pagina is.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"first","type":"text","marks":[{"type":"code"}]},{"text":" de opgegeven ","type":"text"},{"text":"href","type":"text","marks":[{"type":"em"}]},{"text":" wijst naar de eerste pagina van de collectie.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"last","type":"text","marks":[{"type":"code"}]},{"text":" de opgegeven ","type":"text"},{"text":"href","type":"text","marks":[{"type":"em"}]},{"text":" wijst naar de laatste pagina van de collectie.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Headers","type":"text"}]},{"type":"panel","attrs":{"panelType":"note"},"content":[{"type":"paragraph","content":[{"text":"Cached headers worden op dit moment genegeerd, het is ‘by design’ dat Mijn Burgerprofiel zo weinig mogelijk cachet.","type":"text"}]},{"type":"paragraph","content":[{"text":"Is het noodzakelijk om toch te cachen, neem contact met ons op ","type":"text"},{"text":"aansluitingen.mijnburgerprofiel@vlaanderen.be","type":"text","marks":[{"type":"link","attrs":{"href":"mailto:aansluitingen.mijnburgerprofiel@vlaanderen.be"}}]},{"text":".","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Authorization","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Verplicht","type":"text","marks":[{"type":"strong"}]},{"text":" bij een authorisatiemodel.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"De ","type":"text"},{"text":"Authorization","type":"text","marks":[{"type":"code"}]},{"text":"-header wordt gebruikt om API’s te beveiligen, de API-services gebruiken standaard een ","type":"text"},{"text":"Bearer","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"token","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Er worden ","type":"text"},{"text":"geen","type":"text","marks":[{"type":"strong"}]},{"text":" authorisatiegegevens verstuurd via een query parameter: URLs kunnen gecachet worden in de browser en/of gelogd worden. Op deze manier kunnen credentials lekken.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Voorbeeld","type":"text"}]},{"type":"paragraph","content":[{"text":"Authorization: Bearer XyZAbCd1234","type":"text","marks":[{"type":"code"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"CorrelationId en RequestId","type":"text"}]},{"type":"paragraph","content":[{"text":"De CorrelationId en RequestId maken het mogelijk om een set van berichten gelinkt aan een transactie of een uniek bericht binnen een transactie te identificeren. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Het onderstaande schema toont hoe deze 2 waarden gebruikt worden:","type":"text"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"drawio","parameters":{"macroParams":{"zoom":{"value":"1"},"simple":{"value":"0"},"inComment":{"value":"0"},"custContentId":{"value":"1636991834"},"pageId":{"value":"1741750288"},"lbox":{"value":"1"},"diagramDisplayName":{"value":"CorrelationId-and-RequestId.drawio"},"contentVer":{"value":"3"},"revision":{"value":"2"},"baseUrl":{"value":"https://vlaamseoverheid.atlassian.net/wiki"},"diagramName":{"value":"Untitled Diagram.drawio"},"pCenter":{"value":"0"},"width":{"value":"1181"},"links":{"value":""},"tbstyle":{"value":""},"height":{"value":"681"}},"macroMetadata":{"macroId":{"value":"5b823903-61d3-4c0b-a283-95339dddfd66"},"schemaVersion":{"value":"1"},"placeholder":[{"type":"image","data":{"url":"https://ac.draw.io/connectImage?zoom=1&simple=0&inComment=0&custContentId=1636991834&pageId=1741750288&lbox=1&diagramDisplayName=CorrelationId-and-RequestId.drawio&contentVer=3&revision=2&baseUrl=https%3A%2F%2Fvlaamseoverheid.atlassian.net%2Fwiki&diagramName=Untitled+Diagram.drawio&pCenter=0&width=1181&links=&tbstyle=&height=681"}}],"title":"draw.io Diagram"}},"localId":"ec2514bb-2a5f-4cfd-8ffb-76ee0062ee06"}},{"type":"paragraph","content":[{"text":"Door de beide waarden te gebruiken, kunnen specifieke berichten getraceerd worden. In het geval van fouten of vragen kan: ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"de hele transactie gevolgd worden, op basis van de CorrelationId ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"informatie voor een specifiek request geïsoleerd worden, op basis van de RequestId","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"CorrelationId","type":"text"}]},{"type":"paragraph","content":[{"text":"Optioneel","type":"text","marks":[{"type":"strong"}]},{"text":", groepeert 1 or meer berichten in een transactie waardoor berichten traceren doorheen meerdere systemen kan.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Er wordt in de header van de ","type":"text"},{"text":"request","type":"text","marks":[{"type":"strong"}]},{"text":" een ","type":"text"},{"text":"X-Correlation-ID","type":"text","marks":[{"type":"code"}]},{"text":" meegestuurd, in het formaat van een UUIDv4 (bv ","type":"text"},{"text":"a6d87d0e-2454-4501-8110-ecc082aa975f","type":"text","marks":[{"type":"code"}]},{"text":")","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"De waarde in de ","type":"text"},{"text":"respons","type":"text","marks":[{"type":"strong"}]},{"text":" van de ","type":"text"},{"text":"X-Correlation-ID","type":"text","marks":[{"type":"code"}]},{"text":"-header die teruggestuurd wordt, moet gelijk zijn aan de waarde in de request (als deze aanwezig is).","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"RequestId","type":"text"}]},{"type":"paragraph","content":[{"text":"Optioneel","type":"text","marks":[{"type":"strong"}]},{"text":", identificeert elk request op een unieke manier waardoor exacte berichten binnen transacties nauwkeurig aanwijzen kan, zoals bijv. voor support.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Er wordt in de header van de ","type":"text"},{"text":"request","type":"text","marks":[{"type":"strong"}]},{"text":" een ","type":"text"},{"text":"X-Request-ID","type":"text","marks":[{"type":"code"}]},{"text":" meegestuurd, in het formaat van een UUIDv4 (bv ","type":"text"},{"text":"0d1e63a3-b635-4d50-ba7f-34b7176defdf","type":"text","marks":[{"type":"code"}]},{"text":").","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"De waarde in de respons van de ","type":"text"},{"text":"X-Request-ID","type":"text","marks":[{"type":"code"}]},{"text":" -header die teruggestuurd wordt, moet gelijk zijn aan de waarde in de request (als deze aanwezig is).","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Voorbeeld","type":"text"}]},{"type":"codeBlock","content":[{"text":"X-Correlation-ID: 5cd3f329-fe33-4705-8115-e22638eb0f4f\nX-Request-ID: 0b2506d4-14d4-446b-a7a9-3a2944b5efe9","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Standaard foutberichten","type":"text"}]},{"type":"paragraph","content":[{"text":"De foutberichten die teruggeven worden, moeten conform ","type":"text"},{"text":"API-design richtlijnen","type":"text","marks":[{"type":"link","attrs":{"href":"https://data.vlaanderen.be/doc/richtlijnen/iv-rest-api-richtlijnen/#api_design"}}]},{"text":" zijn. Deze zijn gebaseerd op ","type":"text"},{"text":"RFC 7807 - Problem Details for HTTP API's","type":"text","marks":[{"type":"link","attrs":{"href":"https://tools.ietf.org/html/rfc7807"}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Over foutberichten","type":"text"}]},{"type":"paragraph","content":[{"text":"Bij fouten moet de API een correcte HTTP-responscode teruggeven, samen met een payload die voldoet aan RFC 7807, en die het probleem beschrijft. ","type":"text"}]},{"type":"panel","attrs":{"panelType":"success"},"content":[{"type":"paragraph","content":[{"text":"Zorg voor duidelijke en informatieve foutmeldingen. Zo kan Digitaal Vlaanderen ook de afnemers duidelijk informeren.","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Over responscodes","type":"text"}]},{"type":"paragraph","content":[{"text":"Beperkt de responscodes tot de meest courante, in lijn met de richtlijnen van de Expertise Groep Architectuur:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":" ","type":"text"},{"text":"400 Bad Request","type":"text","marks":[{"type":"code"}]},{"text":" De aanvraag heeft invalide parameters en/of de validatie van de aanvraag is gefaald","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":" ","type":"text"},{"text":"401 Unauthorized","type":"text","marks":[{"type":"code"}]},{"text":" Het authenticatietoken van de gebruiker is verlopen","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":" ","type":"text"},{"text":"403 Forbidden","type":"text","marks":[{"type":"code"}]},{"text":" De gebruiker heeft geen toegang tot de resource","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":" ","type":"text"},{"text":"404 Not Found","type":"text","marks":[{"type":"code"}]},{"text":" De specifieke resource is niet gevonden","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":" ","type":"text"},{"text":"500 Internal Server Error","type":"text","marks":[{"type":"code"}]},{"text":" Voor onverwachte fouten in de service die niet opgevangen worden door een andere foutcode","type":"text"}]}]}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Deze lijst is niet limitatief. De API kan extra foutcodes bevatten.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Voorbeeld","type":"text","marks":[{"type":"strong"}]},{"text":" van de structuur voor een foutboodschap:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"HTTP/1.1 404 Not Found\nContent-Type: application/problem+json\nX-Correlation-Id: \"5cd3f329-fe33-4705-8115-e22638eb0f4f\"\nX-Request-Id: \"0b2506d4-14d4-446b-a7a9-3a2944b5efe9\"\n\n{\n \"status\": ,\n \"type\": \"https://foo.vlaanderen.be/errors/\"\n \"title\": \"\",\n \"detail\": \"\",\n \"instance\": \"urn:be.vlaanderen.foo:bar:\" \n}","type":"text"}]},{"type":"paragraph","content":[{"text":"De Expertise Groep Architectuur verplicht het invullen van ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code"}]},{"text":" en ","type":"text"},{"text":"status","type":"text","marks":[{"type":"code"}]},{"text":". Vul ook het ","type":"text"},{"text":"instance","type":"text","marks":[{"type":"code"}]},{"text":" veld in om support te vergemakkelijken. ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"De ","type":"text"},{"text":"instance","type":"text","marks":[{"type":"code"}]},{"text":" parameter dient een URI te zijn volgens de RFC-specs. Gebruik een URN in de vorm van ","type":"text"},{"text":"urn::[]:","type":"text","marks":[{"type":"code"}]},{"text":". De bron-API kan hier vrij invulling aan geven. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"De ","type":"text"},{"text":"error-instance-id","type":"text","marks":[{"type":"code"}]},{"text":" kan een zelf gegeneerde ID zijn (gelinkt aan de fout), de transactieId of de correlatieId.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Bijv.: ","type":"text"},{"text":"urn:be.vlaanderen.mbp:attesten:0b2506d4-14d4-446b-a7a9-3a2944b5efe9","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"},{"text":"Een supportmedewerker kan hieruit snel afleiden dat het over de ","type":"text"},{"text":"attesten","type":"text","marks":[{"type":"code"}]},{"text":"applicatie gaat in ","type":"text"},{"text":"Mijn Burgerprofiel ","type":"text","marks":[{"type":"code"}]},{"text":"(MBP) en dat de errorreferentie ","type":"text"},{"text":"0b2506d4-14d4-446b-a7a9-3a2944b5efe9","type":"text","marks":[{"type":"code"}]},{"text":" is.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Specifieke foutberichten","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"400 Bad Request","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Context","type":"text"}]},{"type":"paragraph","content":[{"text":"De aanvraag heeft ongeldige parameters en/of de validatie van de aanvraag is gefaald. Validatie-errors zijn het gevolg van een businessevaluatie van de payload meegegeven in een voorafgaande API-interactie. Validatie-errors kunnen het verzetten van interactie met (onderdelen van) de API verhinderen.","type":"text"}]},{"type":"paragraph","content":[{"text":"Validatie-errors worden meegegeven als een lijst, met de naam ","type":"text"},{"text":"errors","type":"text","marks":[{"type":"em"}]},{"text":". De elementen van die lijst volgen de basisstructuur van de standaarderrors: ","type":"text"},{"text":"type","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"title","type":"text","marks":[{"type":"code"}]},{"text":" en ","type":"text"},{"text":"detail","type":"text","marks":[{"type":"code"}]},{"text":" zijn verplicht in dit geval. Eigen uitbreidingen zijn toegestaan.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"De client moet de request niet herhalen als er geen wijzigingen zijn.","type":"text"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Referentie","type":"text"}]},{"type":"paragraph","content":[{"text":"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400","type":"text","marks":[{"type":"link","attrs":{"href":"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400"}}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Voorbeeld","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"HTTP/1.1 400 Bad Request\nContent-Type: application/problem+json\nX-Correlation-Id: \"5cd3f329-fe33-4705-8115-e22638eb0f4f\"\nX-Request-Id: \"0b2506d4-14d4-446b-a7a9-3a2944b5efe9\"\n\n{\n \"status\": 400,\n \"type\": \"https://foo.vlaanderen.be/errors/validatie-fout\"\n \"title\": \"Validatie fout\",\n \"detail\": \"U heeft niet alle velden correct ingevuld.\",\n \"instance\": \"urn:be.vlaanderen.foo:bar:fa738431-0b5e-421d-b27a-d341f5cc3a92\"\n \"errors\" : [ {\n \"type\": \"https://foo.vlaanderen.be/errors/validatie-fout/taal\"\n \"title\": \"Taal parameter niet ingevuld\"\n \"detail\": \"Voor het ophalen van dit attest is de taal parameter vereist\"\n }, {\n \"type\": \"https://foo.vlaanderen.be/errors/validatie-fout/nis-code\"\n \"title\": \"NIS code niet ingevuld\"\n \"detail\": \"Voor het ophalen van dit attest is een NIS code vereist\"\n }\n ]\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"401 Unauthorized","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Context","type":"text"}]},{"type":"paragraph","content":[{"text":"Het authenticatietoken van de gebruiker is ongeldig voor deze resource.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Als de gebruiker geen toegang heeft door onvoldoende toestemming moet een ","type":"text"},{"text":"403 Forbidden","type":"text","marks":[{"type":"link","attrs":{"href":"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403"}}]},{"text":"-fout worden teruggegeven.","type":"text"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Referentie","type":"text"}]},{"type":"paragraph","content":[{"text":"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401","type":"text","marks":[{"type":"link","attrs":{"href":"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401"}}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Voorbeeld","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"HTTP/1.1 401 Unauthorized\nContent-Type: application/problem+json\nX-Correlation-Id: \"5cd3f329-fe33-4705-8115-e22638eb0f4f\"\nX-Request-Id: \"0b2506d4-14d4-446b-a7a9-3a2944b5efe9\"\n\n{\n \"status\": 401,\n \"type\": \"https://foo.vlaanderen.be/errors/unauthorized\"\n \"title\": \"Geen toegang tot service\",\n \"detail\": \"Geen of geen geldige authenticatie gegevens in vraag.\",\n \"instance\": \"urn:be.vlaanderen.foo:bar:fa738431-0b5e-421d-b27a-d341f5cc3a92\"\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"403 Forbidden","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Context","type":"text"}]},{"type":"paragraph","content":[{"text":"De gebruiker is correct geauthenticeerd maar heeft geen toegang tot de resource.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Als het token ongeldig is - bijv. omdat het vervallen is - moet een ","type":"text"},{"text":"401 Unauthorized","type":"text","marks":[{"type":"link","attrs":{"href":"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401"}}]},{"text":"-fout worden teruggegeven.","type":"text"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Referentie","type":"text"}]},{"type":"paragraph","content":[{"text":"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403","type":"text","marks":[{"type":"link","attrs":{"href":"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403"}}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Voorbeeld","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"HTTP/1.1 403 Forbidden\nContent-Type: application/problem+json\nX-Correlation-Id: \"5cd3f329-fe33-4705-8115-e22638eb0f4f\"\nX-Request-Id: \"0b2506d4-14d4-446b-a7a9-3a2944b5efe9\"\n\n{\n \"status\": 403,\n \"type\": \"https://foo.vlaanderen.be/errors/forbidden\"\n \"title\": \"Geen toegang tot service\",\n \"detail\": \"De toegang tot de service is geweigerd.\",\n \"instance\": \"urn:be.vlaanderen.foo:bar:fa738431-0b5e-421d-b27a-d341f5cc3a92\"\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"404 Not Found","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Context","type":"text"}]},{"type":"paragraph","content":[{"text":"De resource bestaat niet (voor deze gebruiker). Afhankelijk van de businessrules kan een 404-fout teruggeven worden als er geen data beschikbaar is voor een gebruiker.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Geef een lege collectie terug ipv een 404-fout bij het opvragen van collecties. Bij het ophalen van een specifiek - niet bestaand - item kan een 404-fout wel een geldig antwoord zijn.","type":"text"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Referentie","type":"text"}]},{"type":"paragraph","content":[{"text":"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404","type":"text","marks":[{"type":"link","attrs":{"href":"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404"}}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Voorbeeld","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"HTTP/1.1 404 Not Found\nContent-Type: application/problem+json\nX-Correlation-Id: \"5cd3f329-fe33-4705-8115-e22638eb0f4f\"\nX-Request-Id: \"0b2506d4-14d4-446b-a7a9-3a2944b5efe9\"\n\n{\n \"status\": 404,\n \"type\": \"https://foo.vlaanderen.be/errors/not-found\"\n \"title\": \"Resource niet gevonden\",\n \"detail\": \"De gevraagde informatie is niet beschikbaar.\",\n \"instance\": \"urn:be.vlaanderen.foo:bar:fa738431-0b5e-421d-b27a-d341f5cc3a92\"\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"500 Internal Server Error","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Context","type":"text"}]},{"type":"paragraph","content":[{"text":"Foutcode bij onverwachte fouten in de service die niet worden opgevangen door andere foutcodes.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Als er bij runtime exceptions geen betere fout past, kan deze foutcode gebruikt worden als een ‘last resort’.","type":"text"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Referentie","type":"text"}]},{"type":"paragraph","content":[{"text":"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500","type":"text","marks":[{"type":"link","attrs":{"href":"https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500"}}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Voorbeeld","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"HTTP/1.1 500 Internal Server Error\nContent-Type: application/problem+json\nX-Correlation-Id: \"5cd3f329-fe33-4705-8115-e22638eb0f4f\"\nX-Request-Id: \"0b2506d4-14d4-446b-a7a9-3a2944b5efe9\"\n\n{\n \"status\": 500,\n \"type\": \"https://foo.vlaanderen.be/errors/generic-error\"\n \"title\": \"Er heeft zich een fout voorgedaan!\",\n \"detail\": \"Service tijdelijk onbeschikbaar omdat er een probleem opgetreden is in de service.\",\n \"instance\": \"urn:be.vlaanderen.foo:bar:fa738431-0b5e-421d-b27a-d341f5cc3a92\"\n}","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Security","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"75323bbb-370e-4f8e-9819-3adecf921c8c"}}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"TLS 1.2","type":"text"}]},{"type":"paragraph","content":[{"text":"Alle connecties moet over ","type":"text"},{"text":"https","type":"text","marks":[{"type":"code"}]},{"text":". Gebruik hiervoor TLS 1.2 (Transport Layer Security) of hoger.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Het gebruik van SSLv3, TLS1.0 of TLS1.1 is niet meer toegestaan. Deze versies van het protocol worden onveilig beschouwd.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Authenticatie en autorisatie","type":"text"}]},{"type":"paragraph","content":[{"text":"Standaard verwachten we een Bearer-token in de Authorization header. Meer informatie over Bearer-tokens staat ","type":"text"},{"text":"hier","type":"text","marks":[{"type":"link","attrs":{"href":"https://tools.ietf.org/html/rfc6750"}}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"De structuur van de header: ","type":"text"},{"text":"Authorization: Bearer ","type":"text","marks":[{"type":"code"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"ACM OAuth met burgeridentificatie","type":"text"}]},{"type":"panel","attrs":{"panelType":"success"},"content":[{"type":"paragraph","content":[{"text":"Deze manier van authenticatie is de veiligste en betrouwbaarste manier. We raden dan ook sterk aan dit authenticatiemechanisme te gebruiken.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Hiervoor integreren we met het Vlaams Toegangsbeheer (ACM): ","type":"text"},{"text":"https://overheid.vlaanderen.be/ict/ict-diensten/toegangsbeheer","type":"text","marks":[{"type":"link","attrs":{"href":"https://overheid.vlaanderen.be/ict/ict-diensten/toegangsbeheer"}}]},{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"Start hiervoor als resourceserver een dossier bij ACM en configureer een trustrelatie met Mijn Burgerprofiel. Zo kan Mijn Burgerprofiel een token exchange uitvoeren waarbij de burgerauthenticatie doorvloeit naar de bron. ","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"Zie ook de documentatie van het Vlaams Toegangsbeheer: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://authenticatie.vlaanderen.be/docs/beveiligen-van-api/oauth-rest/rest-namens-gebruiker/rest-token-exchange/"}}]}]},{"type":"paragraph","content":[{"text":"De bron ontvangt een OAuth-token dat via introspection gevalideerd moet worden. De introspection zal ook extra claims teruggeven zoals ","type":"text"},{"text":"rrn","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"given_name","type":"text","marks":[{"type":"code"}]},{"text":" en ","type":"text"},{"text":"family_name","type":"text","marks":[{"type":"code"}]},{"text":" waarmee de bron zowel de applicatie als de burger kan identificeren.","type":"text"}]},{"type":"paragraph","content":[{"text":"Neem contact met ons op om deze aansluiting te starten via ","type":"text"},{"text":"aansluitingen.mijnburgerprofiel@vlaanderen.be","type":"text","marks":[{"type":"link","attrs":{"href":"mailto:aansluitingen.mijnburgerprofiel@vlaanderen.be"}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"MBP OIDC ID Token","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Dit is een fallbackmechanisme voor bestaande integraties. Nieuwe integraties moeten via ","type":"text"},{"text":"ACM OAuth met burgeridentificatie","type":"text","marks":[{"type":"strong"}]},{"text":" gaan. ","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Hiervoor integreren we met het Vlaams Toegangsbeheer (ACM): ","type":"text"},{"text":"https://overheid.vlaanderen.be/ict/ict-diensten/toegangsbeheer","type":"text","marks":[{"type":"link","attrs":{"href":"https://overheid.vlaanderen.be/ict/ict-diensten/toegangsbeheer"}}]},{"text":" en de MBP ID Token Generator (IDTG).","type":"text"}]},{"type":"paragraph","content":[{"text":"Deze integratie is gebaseerd op ","type":"text"},{"text":"OpenID Connect","type":"text","marks":[{"type":"strong"}]},{"text":" en de ","type":"text"},{"text":"autorisatiecode","type":"text","marks":[{"type":"strong"}]},{"text":"flow. De tokenset van ACM wordt via de MBP ID Token Generator omgezet naar een ID Token. Hierdoor kunnen bestaande integraties met minimale aanpassingen de bestaande ACM OIDC ID Token integratie verder gebruiken.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Checks om het token te valideren","type":"text"}]},{"type":"paragraph","content":[{"text":"API's moeten het token met de nodige zorg valideren door de onderstaande checks uit te voeren. De meeste van deze checks gebeuren automatisch - of kunnen makkelijk ingesteld worden. ","type":"text"}]},{"type":"paragraph","content":[{"text":"De meeste OIDC-clients ondersteunen ","type":"text"},{"text":"OIDC Auto Discovery","type":"text","marks":[{"type":"strong"}]},{"text":". Stel dan alleen de autodiscovery-URL in i.p.v. elke URL apart. Dit maakt de implementatie van de OIDC-integratie minder foutgevoelig. ","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"paragraph","content":[{"text":"De ","type":"text"},{"text":"well-known","type":"text","marks":[{"type":"code"}]},{"text":" configuraties staan op deze URL's:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"TNI: ","type":"text"},{"text":"https://tni.idtokengenerator.burgerprofiel.dev-vlaanderen.be/op/.well-known/openid-configuration","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"PROD: ","type":"text"},{"text":"https://idtokengenerator.burgerprofiel.vlaanderen.be/op/.well-known/openid-configuration","type":"text","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph"},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Controleer ","type":"text"},{"text":"de cryptografische handtekening in het Bearer token","type":"text","marks":[{"type":"strong"}]},{"text":" aangeleverd in the ","type":"text"},{"text":"Authorization","type":"text","marks":[{"type":"code"}]},{"text":" header. Gebruik hiervoor de publieke JWKS-endpoint van ACM. De keys kunnen tijdelijk gecachet worden. De JWKS-endpoints zijn beschikbaar op de onderstaande URLS. Refresh de keys bij een ongekende ","type":"text"},{"text":"kid","type":"text","marks":[{"type":"code"}]},{"text":". Zie ook de ","type":"text"},{"text":"OIDC specs","type":"text","marks":[{"type":"link","attrs":{"href":"https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.10.1"}}]},{"text":".","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"TNI","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"https://tni.idtokengenerator.burgerprofiel.dev-vlaanderen.be/op/jwks","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"PROD","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"https://idtokengenerator.burgerprofiel.vlaanderen.be/op/jwks","type":"text","marks":[{"type":"code"}]}]}]}]}]}]},{"type":"paragraph","marks":[{"type":"indentation","attrs":{"level":2}}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Controleer ","type":"text"},{"text":"de geldigheid van het token in de tijd","type":"text","marks":[{"type":"strong"}]},{"text":". Neem een kleine marge (","type":"text"},{"text":"skew","type":"text","marks":[{"type":"code"}]},{"text":") om false-positives te voorkomen. Niet alle klokken lopen tot op de seconde gelijk!","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Controleer de ","type":"text"},{"text":"iat","type":"text","marks":[{"type":"code"}]},{"text":" (issued at)-claim, deze kan niet ","type":"text"},{"text":"na het huidige tijdstip","type":"text","marks":[{"type":"em"}]},{"text":" zijn","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Controleer de ","type":"text"},{"text":"exp","type":"text","marks":[{"type":"code"}]},{"text":" (expiration)-claim, deze mag niet ","type":"text"},{"text":"voor het huidige tijdstip","type":"text","marks":[{"type":"em"}]},{"text":" zijn","type":"text"}]}]}]}]}]},{"type":"paragraph"},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Controleer ","type":"text"},{"text":"de audience","type":"text","marks":[{"type":"strong"}]},{"text":" van het token. Dit kan een lijst met waarden zijn en zou minstens de ","type":"text"},{"text":"audience","type":"text","marks":[{"type":"code"}]},{"text":" voor Mijn Burgerprofiel moeten bevatten:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"TNI: ","type":"text"},{"text":"80689076-8c4a-4bef-abc4-82805e17988d","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"PROD: ","type":"text"},{"text":"88f04968-d331-4ae0-99d9-c6efb845841f","type":"text","marks":[{"type":"code"}]}]}]}]}]}]},{"type":"paragraph"},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Controleer ","type":"text"},{"text":"de uitgever","type":"text","marks":[{"type":"strong"}]},{"text":" van het token, de ","type":"text"},{"text":"issuer","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"TNI: ","type":"text"},{"text":"https://tni.idtokengenerator.burgerprofiel.dev-vlaanderen.be/op","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"PROD: ","type":"text"},{"text":"https://idtokengenerator.burgerprofiel.vlaanderen.be/op","type":"text","marks":[{"type":"code"}]}]}]}]}]}]},{"type":"paragraph"},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Controleer of ","type":"text"},{"text":"het rijksregisternummer ","type":"text","marks":[{"type":"strong"}]},{"text":"voor de aanvraag, dit is de ","type":"text"},{"text":"rrn","type":"text","marks":[{"type":"code"}]},{"text":"-claim in het token. De waarden moeten - na het strippen van spaties, punten en streepjes - exact gelijk zijn om te voorkomen dat gebruikers data ophalen van andere burgers.","type":"text"}]}]}]},{"type":"paragraph"},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Mijn Burgerprofiel creëert zelf de ID-tokens als fallbackmechanisme op basis van de ACM OAuth tokens met burgeridentificatie. Hierdoor moet de bron de Mijn Burgerprofiel IDTG configureren als ","type":"text"},{"text":"Issuer","type":"text","marks":[{"type":"strong"}]},{"text":" en niet ACM.","type":"text"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Waarom een ID-token en geen access token?","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Het ID-token betekent een impliciete autorisatie: alleen de burger kan de flow starten. De autorisatie zelf is echter niet zeker. Die is er alleen omdat een burger toegang heeft tot al zijn/haar persoonlijke informatie.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Whitelisting","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Filter op basis van DNS-naam","type":"text"}]},{"type":"paragraph","content":[{"text":"Uitgaande connecties in Mijn Burgerprofiel zijn gefilterd op basis van de DNS-naam. Geef voor de test- en productie-omgevingen de domeinnamen op waarnaar er geconnecteerd moet worden.","type":"text"}]},{"type":"paragraph","content":[{"text":"Bijv: ","type":"text"},{"text":"https://api.basisregisters.vlaanderen.be","type":"text","marks":[{"type":"code"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"IP-filter","type":"text"}]},{"type":"paragraph","content":[{"text":"Is er IP-filtering actief in test- en/of productie-omgevingen, whitelist dan volgende IP's:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"52.211.93.92","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"34.254.120.143","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"34.246.197.100","type":"text"}]}]}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"Deze IP's kunnen wijzigen.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Zie ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://vlaamseoverheid.atlassian.net/wiki/spaces/AST/pages/1477935810/SystemTeam+IP+Plan#NAT-Gateways"}},{"text":" voor de meest recente lijst en de IP-adressen die van belang zijn.","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Performantie en loadtesten","type":"text"}]},{"type":"paragraph","content":[{"text":"De performantie-eisen zijn verschillend per service. Gebruik de onderstaande tabel als algemene leidraad: ","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"b1410dd9-eded-4e4b-8f2d-b720587b7917"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[276.0]},"content":[{"type":"paragraph","content":[{"text":"Requests per seconde","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableHeader","attrs":{"colspan":1,"background":"#ffffff","rowspan":1,"colwidth":[484.0]},"content":[{"type":"paragraph","content":[{"text":"30","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#f4f5f7","rowspan":1,"colwidth":[276.0]},"content":[{"type":"paragraph","content":[{"text":"Parallelle gebruikers","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[484.0]},"content":[{"type":"paragraph","content":[{"text":"30","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#f4f5f7","rowspan":1,"colwidth":[276.0]},"content":[{"type":"paragraph","content":[{"text":"Gemiddelde respons tijd","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[484.0]},"content":[{"type":"paragraph","content":[{"text":"1 sec","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#f4f5f7","rowspan":1,"colwidth":[276.0]},"content":[{"type":"paragraph","content":[{"text":"90 percentiel","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[484.0]},"content":[{"type":"paragraph","content":[{"text":"2 sec","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#f4f5f7","rowspan":1,"colwidth":[276.0]},"content":[{"type":"paragraph","content":[{"text":"95 percentiel","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[484.0]},"content":[{"type":"paragraph","content":[{"text":"3 sec","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"background":"#f4f5f7","rowspan":1,"colwidth":[276.0]},"content":[{"type":"paragraph","content":[{"text":"Max error rate","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[484.0]},"content":[{"type":"paragraph","content":[{"text":"< 1%","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"De loadtest duurt 20 minuten, waarbij tijdens de eerst 5 minuten een ramp-up gebeurt.","type":"text"},{"type":"hardBreak"},{"text":"Deze loadtesten gebeuren bij voorkeur op een omgeving waar Digitaal Vlaanderen controle heeft over de authenticatie-tokens.","type":"text"}]},{"type":"paragraph","content":[{"text":"Bezorg ons vooraf een lijst met voorbeelddata om te bevragen, meestal in de vorm van een CSV met testrijksregisternummers.","type":"text"}]}],"version":1}