...

Mogelijkheden:

• 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

...

• Hoofdactiviteiten Verenigingsloket, code= hoofdactiviteitenVerenigingsloket

Gebruik van de Beheer API

vCode: waar terug te vinden

Bij het registreren van een nieuwe vereniging (de POST actie op de beheer API) wordt een nieuwe vCode toegekend. Je kan die dan terugvinden in de response header met naam Location. Daar wordt de volledige URL weergegeven om het detail van de nieuwe vereniging op te vragen (API Beheer detail). 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.

Dubbeldetectie

Bij registratie van een nieuwe feitelijke vereniging wordt gecontroleerd of deze mogelijks al bestaat. Als mogelijke dubbels ontdekt worden, krijg je een status 409 terug. In de response body staat dan de lijst van mogelijke dubbels, maar ook een bevestigingstoken.

{
    "bevestigingsToken": "38-4F-88-C5-11-37-83-8A-06-77-D5-34-3B-56-5C-AB",
    "mogelijkeDuplicateVerenigingen": [
        {
            "vCode": "V0001781",
            "naam": "De dubbele vereniging",
            "korteNaam": "Dubbel",
            "hoofdactiviteitenVerenigingsloket": [],
            "doelgroep": "",
            "locaties": [
                {
                    "locatietype": "Correspondentie",
                    "hoofdlocatie": true,
                    "adres": "Dubbelstraat 3, 1234 Dorpegem, België",
                    "naam": "Hoofdgebouw",
                    "postcode": "1234",
                    "gemeente": "Dorpegem"
                }
            ],
            "activiteiten": [],
            "links": {
                "detail": "https://beheer.verenigingen.test-vlaanderen.be/v1/verenigingen/V0001781"
            }
        }
    ]
}

Nu is het de bedoeling dat je je gebruikers laat verifiëren dat de vereniging al dan niet verschillend is van de potentiële dubbels. Om de vereniging alsnog toe te voegen met de gegevens zoals eerder opgegeven, herhaal je dezelfde registreer actie, maar in een request header met naam VR-BevestigingsToken geef je het token mee uit de eerdere respons.

Wanneer het opgegeven token overeenkomt met de inhoud van de request, dan zal de vereniging geregistreerd worden. Komt het token niet overeen, dan krijg je een foutboodschap en status 400 terug.

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

Het verenigingsregister is opgezet als een event-sourced systeem, wat in concreto 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 bij Beheer API

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.

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

1. de header waarde Etag in de response van de lees actie (GET)

   1. Dit geeft de huidige versie aan van de gezochte vereniging

2. 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.

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 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

...