Voortgang ontwikkeling API-standaard voor logging van verwerkingen

juni 2023

Deze API-standaard is in begin 2023 opgeleverd als 1.0 versie. Daarnaast is er een opschalinganalyse uitgevoerd waarin zowel gemeenten als marktpartijen zijn geconsulteerd over functionele- en implementatieaspecten van de standaard. Naast het uitvoeren van een opschalinganalyse is er ook een juridische toetsing uitgevoerd en hieruit heeft zich een vraagstuk voorgedaan dat betrekking heeft op het gebruik van de standaard. VNG onderzoekt wat dit juridische vraagstuk betekent voor de standaard. De verwachting is dat de standaard in de zomer van 2023 als 1.0 versie vastgesteld wordt. Op dat moment zal ook het opschalinganalyserapport en de jurische toetsing worden gepubliceerd. Mocht u in de tussentijd de standaard willen implementeren vragen, vragen wij hiervoor contact op te nemen met de product owner van deze standaard.

22 juli 2021

Opgedane ervaringen met de implementatie van de referentieimplementatie hebben geleid tot een wijziging in de standaard. De Verwerkingenlogging API-standaard is opgedeeld in twee verschillende APIs. Een API voor de bewerking van verwerkingen en een API voor inzage in voorkomens van verwerkte objecten binnen een verwerkingsactie. De API voor bewerkingen wordt gebruikt door procesapplicaties die verwerkingen van (persoons)gegevens vastleggen. De inzage API wordt gebruikt voor het opvragen van voorkomens van verwerkte objecten in het log. De inzage API is bedoeld voor gebruik door informatiesystemen van derden en informatiesystemen die inzage aan betrokkenen geven over verwerkingen die ten aanzien van hun gegevens die plaats hebben gevonden. Een voorbeeld van een dergelijk systeem is een MijnGemeente systeem die na inlog van de burger met DigiD de verwerkingen weergeeft. De scheiding in twee verschillende API’s heeft voordelen op het gebied van privacy-by-design. Het scheiden van de API functies in een deel voor binnengemeentelijk gebruik door procesapplicaties een een deel voor gebruik voor inzage door derden en betrokkenen geeft betere mogelijkheden voor autorisatie van systemen via autorisatie scopes. Hierdoor wordt geborgt dat betrokkenen en derden te allen tijde enkel die gegevens zien die ze mogen zien.

De API voor bewerking van verwerkingen is hier te vinden.
De API voor inzage van verwerkingen door betrokkenen en derden is hier te vinden.

Door de scheiding van de standaard in een Bewerking- en Inzage API zijn de volgende wijzigingen aangebracht:

Scheiding in Github van de twee API’s in Github Pages navigatie en in de folderstuctuur (nu in api-read en api-write folder)
Autorisatiescope ‘read:restricted’ is vervallen. Deze scope is door de functionele scheiding in een bewerking- en inzage API overbodig.
De query parameter ‘beperkteSet’ op de GET is komen te vervallen. De Bewerking API levert altijd een volledige set en de Inzage API levert altijd een beperkte set.
In de ontwerpdocumentatie is de case ‘Inzage door burger – Gegevens die niet langer vertrouwelijk zijn’ komen te vervallen. De Inzage API GET levert altijd alle verwerkingsacties die niet vertrouwelijk zijn. Dat is de combinatie van verwerkingsacties die nooit vertrouwelijk zijn geweest en verwerkingsacties waarvan de vertrouwelijkheid is opgeheven.
Aan de Verwerkte Objecten is een url- en verwerktObjectId attribuut toegevoegd.
In de GET van de Bewerking API is de query parameter ‘beperkteSet’ verwijderd
In de GET van de Bewerking API zijn alle query-attributen optioneel gemaakt

11 mei 2021

De referentieimplementatie van het providerdeel van de API-standaard is gerealiseerd. De referentieimplementatie is te downloaden van Gitlab en kan via een Docker installatie lokaal worden geinstalleerd. Instructies voor de installatie van de referentieimplementatie zijn te vinden op de documentatie website.

14 april 2021

Naar aanleiding van terugkoppeling die het project heeft ontvangen van fouten in het yaml-bestand zijn aanpassingen aan deze definitie gemaakt. Deze wijzigingen leiden tot breaking changes ten aanzien van de versie in de 1.0.0 RC1 release. Om deze reden is besloten een nieuwe release candidate aan te maken (1.0.0 RC2). Wijzigingen die aangebracht zijn hebben onder andere te maken met foutieve lengtes van een aantal velden, wijziging van de manier van doorgeven van het vertrouwelijkheid attribuut, het ontbreken van de foutcode 400 (Bad Request) in de GET van verwerkingacties en incorrect gebruik van minLength bij het attribuut verwerkingsactiviteitUrl. Daarnaast is overbodig commentaar uit het yaml-bestand verwijderd.

25 maart 2021

De FAQ is aangevuld naar aanleiding van de Bijeenkomst API-standaard voor logging van verwerkingen.

6 maart 2021

De RPC calls voor het wijzigen van de Bewaartermijn en Vertrouwelijkheid van verwerkingsacties zijn omgezet naar een PATCH operatie conform REST.

27 januari 2021

In C3677: Inzage door betrokkene is een passage toegevoegd over de noodzaak om ook de inzage van het verwerkingenlog te loggen. Ook in de quickstart guide is toegevoegd dat dit moet en wordt naar deze casus verwezen.
In de quickstart guide en op de pagina van de opvragingscases wordt nu verwezen naar C2866 - Detailvraag op basis van BSN – Door een derde partij en naar C0031 - Opvragen van gegevens bij een derde partij omdat deze cases voorzien zijn van een aanvullende toelichting die laat zien hoe de gegevens van de afnemer via de http-header in het log van de aanbieder terechtkomen:

14 januari 2021

Op diverse pagina’s de tekst ‘html header’ gewijzigd naar ‘http header’.

8 januari 2021

Architectuurschets bij case C2866 - Detailvraag op basis van BSN – Door een derde partij toegevoegd.

7 januari 2021

Aanbeveling toegevoegd inzake gebruik van de autorisatie API uit het ZGW project.

6 januari 2021

Kleine verbeteringen aan navigatie binnen de site. Sitemap is weggehaald en voor zover relevant geintegreerd in de pagina over de achtergrond documentatie.
Casus toegevoegd ivm handmatige verwerking van gegevens.

18 december 2020

Architectuurschets bij case C0031 - Opvragen van gegevens bij een derde partij toegevoegd.

17 december 2020

Architectuurschetsen van inrichtingsscenario’s toegevoegd. Deze schetsen geven inzicht in de verschillende mogelijkheden die gemeenten hebben bij de inrichting van de informatiesystemen die een rol spelen bij logging van verwerkingsactiviteiten en het ontsluiten van die gegevens naar burgers.
Naar aanleiding van ingediend issue in de tekst van de aanvullende specificatie van de GET /verwerkingsacties duidelijker omschreven dat het filteren op Objecttype, Soort Object ID en Identificator feitelijk zorgt dat er op personen gefilterd wordt.
Naar aanleiding van ingediend issue in de specificatie van het attribuuttype Moment aangegeven dat de tijdzone verplicht is en dat de provider deze opslaat zoals aangereikt en dus niet omrekent.

16 december 2020

Datatype van Bewaartermijn is gewijzigd van Aantal Jaar in Periode. In de API moet dit nog vertaald worden naar xs:duration.
Gegevenswoordenboek aangevuld met Verwerkingsactiviteit URL en Verwerkingactiviteit URL Afnemer. Deze attributen waren al verwerking in de afbeeldingen en in de API maar ontbraken nog in gegevenswoordenboek.
Besluit B7259 stelde nog dat de consumer aan de provider geen doelbinding mee geeft. Inmiddels is dat wel mogelijk via de http header. Essentie van het besluit is echter dat de provider de doelbinding van de consumer niet kan gebruiken om zelf te loggen. Het besluit is aangepast om aan te geven dat de doelbinding (in de vorm van een verwerkingsactiviteit) wel meegegeven kan worden via de http header maar dat de provider moet loggen op basis van een eigen doelbinding.

2 december 2020

De API pagina is aangepast op de volgende punten:

Verwijzing naar Quick Start Guide opgenomen.
Eerst worden functies opgesomd. Per functie is een beschrijving beschikbaar en een uitleg hoe de mapping is met de API en welke autorisatiescope gebruikt moet worden.
De API-calls worden daarna opgesomd. Per call is een aparte aanvullende specificatie opgenomen.

1 december 2020

Quick Start Guide toegevoegd.

23 november 2020

Autorisaties (scopes) toegevoegd aan de Verwerkingsacties API zodat alle logging-functies gemapped kunnen worden op de API calls.

Beschrijvingen van de scopes toegevoegd.
Resources in de OAS-specificatie.
Mapping-tabel uitgebreid met een extra kolom voor de scopes zodat alle logging-functies gemapped kunnen worden.

18 november 2020

Verwerkingsactie.Vervallen verwijderd uit specificaties van opvragingsfuncties. Alle getourneerde verwerkignsacties zijn niet vervallen dus attribuut heeft geen meerwaarde. (OAS was al correct).

16 november 2020

OAS in overeenstemming gebracht met het informatiemodel en UGM. Onder andere:

Lengte van namen opgerekt van 80 naar 242.
Voor OIN een reguliere expressie toegevoegd conform gegevenswoordenboek
Her en der velden toegevoegd, aangepast of verwijderd om de API in overeenstemming te brengen met het informatiemodel
Her en der velden in andere volgorde gezet om API in overeenstemming te brengen met het informatiemodel
Her en der foutjes met camelCase opgelost.

11 november 2020

Inhoudelijke aanpassingen:

Verwerkingsactie.Afnemer was een OIN. Dit hebben we moeten omzetten naar een Soort ID/ID constructie omdat de afnemer ook een natuurlijk persoon kan zijn (zie case 2521). Dit raakt alle afbeeldingen van het gegevensmodel en de API waarin het attribuut afnemer voorkomt. Ook de tekst van besluit B9330 ‘Opname van afnemer’ is aangepast zodat deze weer aansluit bij de wijziging.
Attribuuttype Naam: Lengte van 80 naar 242.
Attribuuttype OIN: Formeel patroon in de vorm van een regular expression toegevoegd.
Attribuuttype UUID: Formeel patroon in de vorm van een regular expression toegevoegd.
Aanwezigheid van http header attributen toegelicht. N.B. Bovenstaande aanpassingen moeten nog doorgevoerd worden in de API.

Correcties:

De nieuwe http header attributen (verwerkingsactiviteit id en url) zijn toegevoegd aan besluit 9177.
De resourcenaam wijziging was nog niet doorgevoerd op de toelichtingspagina over de API.

Tekstuele aanpassingen:

Case 2521: ‘Inzage van gegevens aan de balie’ aangepast. Gaat niet langer alleen over derden, kan ook de burger zelf zijn. Gevolg is dat we het BSN van de burger als afnemer moeten kunnen vastleggen.
Case 9041: ‘Notificaties – Informatiearm’. Kleine tekstuele verduidelijkingen.
Case 9299: ‘Synchronisatie naar BGL’. BGL = Binnengemeentelijke Levering.
Logging Maturity Level: Kleine verbetering aan leesbaarheid schema met de verschillende niveau’s.

8 november 2020

Casing van http header attributen gecorrigeerd.

6 november 2020

In de alle beschrijvingen ‘het log’ gewijzigd in ‘het verwerkingenlog’ om duidelijk te maken dat het enkel over de logging van verwerkingen gaat.

1 november 2020

De resource Actie hernoemd naar Verwerkingsactie.
De attributen Actie.Id en Actie.Naam hernoemd naar Verwerkingsactie.ActieId en Verwerkingsactie.ActieNaam.
Het attribuut Verwerkingsactie.VerwerkingsactiviteitUrl toegevoegd.
Het attribuut Verwerkingsactie.VerwerkingsactiviteitIdAfnemer en Verwerkingsactie.VerwerkingsactiviteitUrlAfnemer toegevoegd.
De http header attributen uitgebreid met Verwerkingsactiviteit ID en Verwerkingsactiviteit URL.

28 oktober 2020

Update van afbeeldingen van informatie- en gegevensmodel.
Update van API beschrijvingen.
Site index toegevoegd.

26 oktober 2020

Enkele foutieve links in pagina’s opgelost.

15 oktober 2020

Uitgangspunten die gehanteerd zijn bij de totstandkoming van de API-standaard beschreven en gerelateerd aan ontwerp artefacten.
Excel overzicht van de verschillende ontwerpartefacten per case toegevoegd.

12 oktober 2020

Beschrijvingen van de tot de standaard behorende API functies toegevoegd.
Case beschrijvingen toegevoegd voor:
Diverse tekstuele aanpassingen in ontwerpbesluiten.

8 oktober 2020

Case beschrijvingen voor het opvragen van gegevens toegevoegd.

7 oktober 2020

Case beschrijvingen voor het bijhouden van gegevens toegevoegd.

oktober 2020

Concept Gegevensmodel gepubliceerd.
Concept Gegevenswoordenboek gepubliceerd.
Ontwerpbesluiten toegevoegd.
Aanbevelingen toegevoegd.
Lijst van brondocumenten toegevoegd.
Lijst van openstaande vraagstukken toegevoegd.