Zie ook: https://documentatie.burgerprofiel.vlaanderen.be/attesten/index.html
Bronnen vs. afnemers
Bij widgets, dossierstatusinformatie (DOSIS) en notificaties werken we met “afnemers” die communiceren met de API die Digitaal Vlaanderen bouwt en documenteert.
Voor attesten en vergunningen, formulieren en generieke WWOOM-bronnen werken we met “bronnen”, dat is de API van de klanten die Digitaal Vlaanderen aanspreekt. Hierbij voorziet Digitaal Vlaanderen documentatie over hoe we de bron bevragen die ze moeten implementeren in hun software.
Het doel van de documentatie is dan om het contract dat we gaan spreken met hun zo duidelijk mogelijk te maken zodat zij weten hoe wij hun gaan bevragen, gezien zij deze API moeten implementeren in hun software.
Wij hebben gekozen voor deze aanpak om het mogelijk te maken om op een gestandaardiseerde manier veel klanten aan te sluiten zonder veel aanpassingen aan onze kant voor iedere klant (soort van gedistrubeerde aanpak, iedereen doet een beetje werk), we dienen enkel nog de klant te configureren (metadata over waar hun server te vinden is, ...)
Huidige attesten documentatie staat op https://documentatie.burgerprofiel.vlaanderen.be/attesten/index.html ik heb nog niet gevonden waar de ‘source’ daarvan is, dat is nog door mijn voorganger gemaakt, ik zal eens checken bij Frederic of hij dat toevallig weet. Maar sowieso best dat het op confluence komt zoals de rest, beetje eenheid creëren.
Er zijn 3 puntjes aan de oude documentatie:
Security luik moet geupdate worden, we gebruiken nu https://tni.idtokengenerator.burgerprofiel.dev-vlaanderen.be/ ipv https://authenticatie-ti.vlaanderen.be voor TNI en https://idtokengenerator.burgerprofiel.vlaanderen.be/ ipv https://authenticatie.vlaanderen.be/ voor PROD
Een wederkerend “probleem” bij de aansluiters die de huidige documentatie lezen is dat ze denken dan ze de structuur van de voorbeeld URLs exact moeten overnemen. Ergens staat er in de documentatie “A typical URL for your endpoint would look like: [https://%3chostname%3e/v1/certificates/%3cssn%3e?limit=10&page=0]https://<hostname>/v1/certificates/<ssn>?limit=10&page=0” en dat nemen ze dan nogal letterlijk, ondanks de referentie naar HATEOAS en de beknopte uitleg. Wij hoeven enkel een entry-point in de applicatie te hebben en wij verwachten dat je daarbij enkele standaarden volgt (versie in het pad, limit en offset parameters).
De oude documentatie is in het engels geschreven, terwijl er ondertussen uitgeklaard is dat documentatie wel degelijk aan de taalwetgeving onderhevig is en dus primair in het nederlands moet staan. (zie https://vlaamseoverheid.atlassian.net/wiki/spaces/EAA/pages/2044103128/Taal+van+documentatie+en+APIs)
Voor de API specificaties, versie 2 is inhoudelijk nog niet klaar. Ik heb vorig jaar een eerste versie geschreven en daar ben jij wel al eens door gegeaan dacht ik.
Het is wel handig om daar eens met jou door te gaan, zodat het concept duidelijk is. Het idee is dat daar een aantal algemene regels in opgenomen worden zoals security, error handling, headers, ... zodat dat niet iedere keer opnieuw geschreven moet worden.
Dat is enerzijds geschreven om onze eigen teams en developers een handleiding te geven hoe we verwachten dat onze APIs er uit zien en reageren, maar anderzijds is dat ook een goede leidraad voor bronnen en afnemers.
De API specificaties zijn in essentie een doorontwikkeling op de richtlijnen uit de expertise groep architectuur Informatie Vlaanderen REST API richtlijnen versie 1.3