Zie ook: https://documentatie.burgerprofiel.vlaanderen.be/attesten/index.html
Waar dat we bij notificaties en dosis (push) en widgets we spreken over afnemers, praten we hier eerder over bronnen. Het is een subtiel verschil. Bij de anderen spreken de afnemers tegen een API van ons die wij bouwen en zij aanspreken, er is dus een bestaande API die wij documenteren voor hun om te gebruiken.
Voor attesten, formulieren en generieke WWOOM bronnen is dat anders, daar is de klant de bron en spreken wij tegen hun API. 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