| Table of Contents | ||||
|---|---|---|---|---|
|
...
Registreren van een nieuwe vereniging
Wijzigen van de gegevens van een vereniging
Zoeken naar een vereniging op basis van naam, postcode, gemeente
Alle gegevens van een vereniging opvragen
Historiek opvragen van een vereniging
...
Gebruik van de Publieke API
vCode: formaat
De unieke identificatie van een vereniging is de vCode. Dit is een code die begint met de letter V (van Vereniging) gevolgd door 7 cijfers. Die cijfers hebben geen betekenis en worden gewoon sequentieel toegekend, startend vanaf 1001. Voorbeeld: V0001042.
Gebruik van de Publieke API
Codelijsten
Codelijsten = lijsten met mogelijke waarden voor een bepaald veld, kunnen opgevraagd worden via de publieke API. 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
De publieke API bevat een ZOEK functionaliteit. 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
...
Zoek opdrachten
De publieke API bevat een ZOEK functionaliteit. 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 |
q=naam:vereniging AND locaties.postcode:9000 | Je kan 2 criteria combineren met |
Codelijsten
Om deze functionaliteit te gebruiken, heb je geen API Key nodig.
Codelijsten = lijsten met mogelijke waarden voor een bepaald veld, kunnen opgevraagd worden via de publieke API. 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
Gebruik van de Beheer API
...
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.
...
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)
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, …)
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.
| Note |
|---|
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. |
...