Veel gestelde vragen verenigingsregister

vCode: waar terug te vinden

Bij het registreren van een nieuwe vereniging (POST organisaties/verenigingen/verenigingen/feitelijkeverenigingen - v1 ) wordt een nieuwe vCode toegekend. Je kan die terugvinden in de response header met naam Location. Daar wordt de volledige URL weergegeven om het detail van de nieuwe vereniging op te vragen.

Voorbeeld URL in Location:

https://iv.api.test-vlaanderen.be/api/v1/organisaties/verenigingen/verenigingen/V0001060

Om enkel de vCode te verkrijgen, kan je van die URL de laatste 8 karakters nemen of (nog beter) alles wat na de laatste / komt. (bijvoorbeeld V0001060)

Codelijsten opvragen

De codelijsten kan rechtstreeks worden opgevraagd via het publieke API van verenigingsregister. Je hebt daarvoor geen credentials nodig.

Het formaat van de API call = https://<publieke URL>/v1/<Code>, zoals bijvoorbeeld https://publiek.verenigingen.staging-vlaanderen.be/v1/hoofdactiviteitenVerenigingsloket.

De codelijsten die je nu kan opvragen zijn:

Hoofdactiviteiten Verenigingsloket, code= hoofdactiviteitenVerenigingsloket

Zoek opdrachten

Specifiek voor Beschrijving Vraag (GET organisaties/verenigingen/verenigingen/zoeken - v1)

Deze zoek functionaliteit is een elastic search implementatie. De zoekcriteria kan je dus samenstellen zoals je bij elastic search zou doen. Hierbij enkele voorbeelden:

Query	Wat is het resultaat?
q=*	Alle verenigingen in het verenigingsregister
q=vereniging	Alle verenigingen die ergens de tekst vereniging in een zoekveld hebben staan. Dat kan in de naam zijn, maar evengoed in een ander veld dat beschikbaar is in de zoek resultaten
q=naam:vereniging	Alle verenigingen die het woord vereniging in hun naam hebben. Het moet wel degelijk het volledige woord zijn dat er in zit: “Vereniging van zoekers” zal teruggevonden worden, maar “Zoekvereniging” niet.
q=naam:bal	Alle verenigingen die ergens in hun naam het woord bal hebben. In dit geval kan het ook in het midden van het woord zitten. Zo zal ook de vereniging met naam “voetbalclub de sjotters” in de resultaten aanwezig zijn
q=doelgroep.minimumleeftijd:<=16	alle verenigingen die een waarde hebben in het veld `doelgroep.leeftijd` die kleiner of gelijk is aan 16.
q=naam:vereniging AND locaties.postcode:9000	Je kan 2 criteria combineren met `AND`, `OR` en ook met haakjes `()`

Gebruik van PATCH voor wijzigingen

Om gegevens te wijzigen, wordt een PATCH opdracht gebruikt. Dit biedt je de mogelijkheid om enkel de waarden mee te geven die aangepast moeten worden. De andere velden kan je meegeven, maar dat hoeft niet. De waarden die niet mee in de API call staan blijven hun huidige waarde behouden.

Zo kan je bijvoorbeeld op niveau van de vereniging enkel de korteNaam meegeven om enkel deze waarde aan te passen. Al de andere waarden blijven ongemoeid.

korteNaam: “VR” → zal de waarde aanpassen naar “VR”
korteNaam: null → wordt hetzelfde geïnterpreteerd als wanneer je dit veld niet zou opgeven
korteNaam: ““ → zal het veld korte naam leeg maken

Om een veld leeg te maken moet het expliciet op een lege waarde ("" of []) gezet worden.

{
  "legeString": "",
  "legeDatum": "",
  "legeArray": [],
  "legeBooleanKanEigenlijkNiet": false,
  "leegObject": {}
}

Een waarde in de PATCH opdracht die exact gelijk is aan de waarde zoals die momenteel gekend is, zal die waarde ook niet aanpassen. Daarvan is dus ook geen spoor terug te vinden in de historiek van de vereniging.

Wanneer je in een PATCH opdracht een array van waarden aanpast (zoals bvb hoofdactiviteitenVerenigingsloket), dan wordt er verwacht dat alle gegevens van die array opnieuw opgegeven worden, ook al verandert er maar 1 item. De gegevens van de vereniging zullen in hun geheel vervangen worden door hetgeen opgegeven wordt in de patch call.

Event-Sourced systeem

Bij de bron is het verenigingsregister opgezet als een event-sourced systeem.

Het betekent dat de schrijf activiteiten (registreren van nieuwe vereniging, wijzigen van een naam, …) gescheiden worden van de lees-activiteiten (vraag detail gegevens op van een vereniging, zoek verenigingen, …).

Bij elke schrijf actie worden de opgegeven waarden volledig gecontroleerd en krijg je al een OK (status 202 of 200) terug wanneer het event zelf in orde is. Dat wil nog niet zeggen dat de lees-functionaliteiten op dat moment al aangepast zijn. Achterliggend wordt de impact van elk event op de lees-functionaliteiten een voor een aangepakt, waarna het systeem opnieuw volledig consistent is met de vraag. Dit heet eventual consistency.

Naamgeving:

Schrijf acties noemen we events
Lees functionaliteiten noemen we projecties

expectedSequence

Het tijdsverschil tussen het event en het aanpassen van alle projecties is zeer kort, meestal minder dan 1 seconde zelfs, maar toch kan het zijn dat 2 opeenvolgende API-calls (eentje om te schrijven en eentje om te lezen) zo kort op elkaar volgen dat de 2e het effect van de eerste nog niet meeheeft. Daarom is volgend mechanisme beschikbaar:

in het resultaat van de 1e API-call , in de response headers, staat een veld VR-Sequence. Dat is een oplopend versie nummer van de ontvangen events.

Bij het oproepen van de 2e API-call, waarbij je de waarde van een projectie opvraagt, kan je een parameter meegeven in de URL expectedSequence. Daarmee geef je aan dat je de waarde wil zien na het toepassen van (minstens) het event met het opgegeven nummer.

Wanneer de projectie nog niet is aangepast met de effecten van het opgegeven event, dan krijg je een response status 412 - precondition failed. In dat geval moet je even wachten en de call opnieuw proberen tot je een response status 200 - OK terug krijgt.

Wanneer je de parameter expectedSequence niet opgeeft, wordt steeds de op dat moment geldende waarde van de projectie meegegeven.

Deze parameter is enkel beschikbaar in de Beheer API - bij opvragen van beheer detail en beheer historiek dus. De publieke API heeft deze parameter niet.

Voorbeeld:

1e call

PATCH <BasisURL>/v1/verenigingen/<vCode>
{
    "naam": "Nieuwe naam"
}

Response status: 202
Response header: VR-Sequence: 254

2e call

GET <BasisURL>/v1/verenigingen/<vCode>?expectedSequence=254

Concurrency bij schrijf-acties

We willen situaties vermijden waarbij 2 beheerders eenzelfde vereniging tegelijkertijd aanpassen. Dat zou kunnen leiden tot een situatie waar de 2e beheerder de waarden van de 1e beheerder overschrijft. Om dit correct te laten verlopen, vragen we elke beheerder om gebruik te maken van

de header waarde Etag in de response van de lees actie (GET)
1. Dit geeft de huidige versie aan van de gezochte vereniging
de header If-Match te gebruiken in de request van de schrijf-actie (PATCH, PUT, …)
1. hiermee geef je aan dat je enkel wil aanpassen indien de huidige waarde nog steeds overeenkomt met de eerder opgevraagde versie

Wanneer de opgegeven waarde in If-Match nog steeds overeenkomt met de huidige versie van de vereniging, dan wordt het event verwerkt en krijg je een status code 202 of 200. In die response header staat het nieuwe versie nummer van de vereniging. Dit is nuttig wanneer je meerdere events na elkaar wil lanceren voor dezelfde vereniging.

Wanneer de opgegeven waarde in If-Match niet overeenkomt met de huidige versie van de vereniging, krijg je een status code 412 - precondition failed terug.

Wanneer je de If-Match header niet gebruikt, wordt de waarde van de vereniging sowieso overschreven en loop je dus het risico van de waarden van andere beheerders te overschrijven.

Voorbeeld scenario

Tijdstip	Beheerder 1	Beheerder 2
t1	GET vCode V0001001 → ETag = W/”123”
t2		GET vCode V0001001 → ETag = W/”123”
t3	PATCH vCode V0001001 Header: If-Match: W/”123” → OK , Etag is nu W/”124”
t4		PATCH vCode V0001001 Header: If-Match: W/”123” → NOK , status code 412

Response code 200 bij schrijfacties + impact op VR-sequence en ETag

Wanneer een schrijf actie succesvol eindigt, wordt standaard een response code 202 teruggestuurd. Dit betekent: “OK we hebben je aanvraag tot wijziging aanvaard”.

Wanneer je echter vraagt om iets te wijzigen dat reeds op die manier gekend is in het verenigingsregister, dan wordt er een status code 200 teruggestuurd. Dit betekent gewoon “OK” want eigenlijk moet er niets gebeuren.

Dit mechanisme komt op 2 plaatsen voor:

Wanneer alle waarden in de PATCH exact gelijk zijn aan de waarden zoals die gekend zijn, dan gebeurt er dus eigenlijk niets. Om dit te reflecteren, krijg je op dat moment een status code 200 - OK terug in plaats van de standaard status code 202 - aanvaard.
Wanneer je een KBO vereniging wil registreren terwijl dat KBO-nummer al gekend is, dan wordt ook een status 200 OK teruggegeven. In de header location staat dan de vCode waaronder die KBO vereniging al gekend is.

Omdat er geen wijziging heeft plaatsgehad, zal deze API call ook geen velden VR-Sequence noch ETag terugsturen (zie de secties hierboven voor de betekenis van deze headers). Als die noodzakelijk zijn voor de verdere verwerking in je toepassing, kan je deze waarden steeds ophalen via een API call naar beheer detail van die vereniging.

Manieren om een adres op te geven

Om een adres op te geven als locatie van een vereniging, kan je op 3 manieren tewerk gaan:

adres met adrescomponenten
adresID met de identificator uit het adresregister
de combinatie van beide methoden hierboven

Wanneer je een adres opgeeft met adrescomponenten, dan zijn de velden straat, huisnummer, postcode, gemeente en land verplicht.

Wanneer je adresId opgeeft, dan moet broncode steeds AR zijn - dit is momenteel de enige bron van adressen die we ondersteunen. Voor het adresregister (AR) moet het veld bronwaarde een URI zijn van het adresregister zoals bijvoorbeeld https://data.vlaanderen.be/id/adres/3706808

Tijdens de verdere ontwikkeling van het verenigingsregister zijn nog enkele uitbreidingen voorzien, zoals (alles onder voorbehoud):

Wanneer adresId opgegeven wordt, gaan we de adres componenten ophalen uit het adresregister
Wanneer een adres met componenten gedefinieerd wordt, gaan we gebruik maken van de adresmatch APÏ van het adresregister om te proberen om hier een adresId van op te halen
Wanneer beide opgegeven worden, dan checken we dat de adrescomponenten overeenkomen met het de waarden die we uit het adresregister halen op basis van het adresId.

Beheren van de doelgroep leeftijd

Het object doelgroep is een classificatie gebaseerd op leeftijd. Hierbij kan je twee waarden opgeven: minimumleeftijd en maximumleeftijd. Beide waarden zijn optioneel. De default waarden zijn 0 voor de minimumleeftijd en 150 voor de maximumleeftijd.

"doelgroep": {
    "minimumleeftijd": 7,
    "maximumleeftijd": 77
}

Wanneer je doelgroep opgeeft, dan moet je telkens beide waarden opgeven. Zo niet wordt de waarde die je niet opgeeft gereset naar de default waarde. Voorbeeld: hier wordt de leeftijdsrange op [8-150] gezet.

"doelgroep": {
    "minimumleeftijd": 8
}

Je kan de leeftijdsrange ook volledig terugzetten naar de default waarden door een leeg object doelgroep op te geven. In dit voorbeeld wordt de range gewijzigd naar [0-150]

"doelgroep": {}

Verduidelijking over de gebeurtenissen in de historiek van een vereniging

De historiek van een vereniging GET organisaties/verenigingen/verenigingen/{vCode}/historiek - v1 geeft zicht op de wijzigingen op de verenigingsdata zoals terug te vinden in het register.

De gebeurtenissen met naam “xxxWerdGewijzigd” betekenen voor de basisgegevens het volgende:

data werd toegevoegd (na registratie) → Wijziging van een lege waarde naar een ingevulde waarde
data werd gewijzigd → van ingevulde waarde naar een andere ingevulde waarde
data werd verwijderd → van een ingevulde waarde terug naar een lege waarde

Contactgegevens, locaties en vertegenwoordigers maken geen onderdeel uit van de basisgegevens. Wijzigingen op deze data genereren gebeurtenissen met de namen “WerdToegevoegd”, “WerdGewijzigd” en “WerdVerwijderd”.