Unieke sleutels voor items in Catalogus API

[w-van-weelden]

Resources in de Catalogus API zijn uniek bekend via hun UUID. In combinatie met de URL, zorgt dit dat een resource uniek kan worden teruggevonden. Maar de URL van een element kan wijzigen bij een nieuwe versie. Dit is een prima keuze wanneer een medewerker vanuit een interface een keuze maakt uit een lijst. Veel communicatie tussen systemen verloopt echter op de achtergrond. Wanneer eenmalig statustypen, zaaktypen en documenttypen zijn ingericht, bijvoorbeeld in een workflow, verloopt de communicatie geautomatiseerd. Deze manier van werken van applicaties heeft gevolgen voor de werking/gebruik van de API.

Resources in de Catalogus API hebben naast de UUID (die alleen werkt met een URL-referentie) alleen een omschrijving. Wanneer een applicatie wordt ingericht, moet er gekozen worden om danwel een URL-referentie, danwel een omschrijving op te slaan. Dit zorgt voor veel extra verkeer en is foutgevoelig.

Voor leveranciers is het bijna verplicht om van elke resource (zaakstatus, zaaktype, documenttype) de URL resource op te slaan in de database.

• URL-referentie: Door een URL-referentie op te slaan wordt altijd de juiste referentie meegegeven en worden onhandige zoekopdrachten voorkomen. Echter, de UUID’s zijn uniek per omgeving. Tussen een testomgeving en een productieomgeving kunnen de UUID’s verschillen. Dit betekent dat de inrichting niet kan worden gekopieerd van test naar productie en vice versa. Dit leidt tot extra inrichtingsactiviteiten en extra kosten voor gemeenten.
• Omschrijving: Bij een omschrijving moet er voor elke zaak update eerst in de Catalogus API de juiste URL-referentie worden opgehaald. Via een search scope moeten eerst alle elementen, zoals zaaktypen worden opgehaald. Op basis van een omschrijving moet vervolgens worden ge-matched welk element de juiste is, zodat de URL-referentie kan worden bepaald. Dit is een dure operatie en vereist dat elke leverancier deze matching in elk pakket moet inbouwen. Dat leidt tot extra werk en extra kosten.

Om een goede integratie mogelijk te maken, is het belangrijk dat een type altijd een unieke sleutel heeft die gelijk is tussen omgevingen. Een UUID kan deze rol vervullen, wanneer de UUID gelijk kan zijn binnen de testomgeving en de productie-omgeving en als de UUID hetzelfde blijft bij nieuwe versies van de gegevens. Als alternatief kunnen unieke, functionele codes toe te voegen bij alle elementen in de Catalogus API om direct de URL referentie met één call op te halen.

Op aanvraag van VNG-R in het groeipactoverleg dit als apart item opgevoerd. Er zijn enkele gerelateerde items. Die staan echter al zo lang open, dat ik een nieuwe open om het onder de aandacht te brengen.

• Catalogi API 1.0.0 heeft bij Zaaktype een uniciteit op catalogus+omschrijving ipv catalogus+identificatie #1639
• Als Consumer wil ik Zaaktypen kunnen zoeken op basis van attributen omdat ik de URL naar het zaaktype als referentie moet opnemen bij de zaak #1650
• Cataogi API mist filters op unieke elementen om deze er uit te halen #1820

[michielverhoef]

Maar de URL van een element kan wijzigen bij een nieuwe versie

Dit is ook exact de bedoeling. Hiermee kan ondubbelzinnig naar de specifieke versie van een resource verwezen worden.

Om een goede integratie mogelijk te maken, is het belangrijk dat een type altijd een unieke sleutel heeft die gelijk is tussen > omgevingen. Een UUID kan deze rol vervullen, wanneer de UUID gelijk kan zijn binnen de testomgeving en de productie-
omgeving en als de UUID hetzelfde blijft bij nieuwe versies van de gegevens. Als alternatief kunnen unieke, functionele
codes toe te voegen bij alle elementen in de Catalogus API om direct de URL referentie met één call op te halen.

De UUID zal wijzigen wanneer een nieuwe versie van een resource gemaakt wordt. Ook dit is weer precies wat er beoogd is.

Die staan echter al zo lang open, dat ik een nieuwe open om het onder de aandacht te brengen.

Dat klopt. Er wordt op dit moment heel hard gewerkt aan de nieuwe versies van de API's. Tot die versies beschikbaar zijn zullen deze issues open blijven staan. Om te voorkomen dat de dicsussie versnippert over verschillende issues stel ik voor dit issue te sluiten en de discussie bij de reeds bestaande issues te voeren.

[w-van-weelden]

Dat een UUID gebruikt moet worden voor een unieke versie kan. Dat betekent wel dat het opslaan van UUID/URL's naar informatie in de Catalogus API geen goede oplossing is. Bij elke update moet je dan opnieuw de inrichting doen.

In dat geval zou het goed zijn om voor elk gegeven een unieke, functionele code (zoals een zaaktypecode) in StUF toe te voegen. Zodat applicaties via een eenvoudige call altijd de juiste UUID/URL kunnen opvragen. Het gevolg is wel dat de Catalogus API behoorlijk bestookt gaat worden.

Voor zover ik kan overzien, is dit item echter alleen opgelost als de drie gerefereerde items gezamenlijk zijn opgelost. Of missen we dan nog iets?

[sergei-maertens]

Voor zaaktypen bijvoorbeeld heb je identificatie/omschrijving velden die je kan gebruiken als query-parameter om de relevante versie van het zaaktype te vinden. Als je het zaaktype hebt, dan kan je daarmee weer in die context de statustypen etc. opvragen op basis van omschrijving/volgnummer etc.

Het klinkt voor mij dus alsof er een oplossing voor je problemen is.

[w-van-weelden]

Wellicht is er enige verwarring over versies. De UUID van een zaaktype wijzigt bij een nieuwe versie. En Michiel merkt hier oop dat dit ook de bedoeling is. “Hiermee kan ondubbelzinnig naar de specifieke versie van een resource verwezen worden”. Hier ontstaat verwarring over versies want ik heb het over versies van API’s en Michiel heeft het over versies van resources.

De UUID duidt de resource uniek aan, terwijl de URL de combinatie van API versie en resource uniek aanduidt. Met name voor hergebruik van een ingerichte catalogus is het dan van belang dat de UUID’s gelijk blijven. Dat is volgens mij de kern van dit issue. Zouden jullie daar nog op willen reageren?

Dat een UUID wijzigt bij een nieuwe versie van de resource lijkt mij alleen maar goed. Maar als bv. een zaak is gestart op basis van een gekoppeld zaaktype versie x, dan moet die zaak aan zaaktype versie x blijven hangen, ook als er daarna van dat zelfde zaaktype een versie y wordt aangemaakt. En dat is precies wat je bereikt met unieke UUID’s. Maar Joeri heeft natuurlijk ook een punt in #1820. Een gebruiker die een zaak wil aanmaken moet kunnen zoeken op de omschrijving van het zaaktype en dan de laatste versie vinden. De opmerking van Sergei is eigenlijk een antwoord op het issue van Joeri en net op het issue dat ik aangeef.

[michielverhoef]

De UUID duidt de resource uniek aan, terwijl de URL de combinatie van API versie en resource uniek aanduidt. Met name voor hergebruik van een ingerichte catalogus is het dan van belang dat de UUID’s gelijk blijven. Dat is volgens mij de kern van dit issue. Zouden jullie daar nog op willen reageren?

Ik denk dat hier toch sprake is van enige verwarring: De unieke aanduiding van een versie van een resource bestaat uit de url, waar de UUID onderdeel van is.

Het attribuut url bevat dus ook de UUIID. Bij een nieuwe versie van een zaaktype (of andere resource) krijgt deze nieuwe versie een nieuwe UUID. Ook migratie naar een nieuwe versie van de API leidt tot nieuwe versies van de resources, met een nieuwe UUID.

Dit maakt het onderhoud en gebruik allemaal zeer bewerkelijk en in de praktijk niet heel erg bruikbaar. Daar zijn we inmiddels achter gekomen. Daarom is in Catalogi API 1.2 het versie model uit ImZTC geintroduceerd en is het mogelijk om op basis van zaaktype-identificatie en datumGeldigheid een zaaktype op te vragen. De Catalolgi API geeft dan de versie van het zaaktype (inclusief verwijzingen naar de correcte versies van roltype, statustype etc.) terug zoals dat geldig was ten tijde van de opgegeven datumGeldigheid.
Zie ook https://vng-realisatie.github.io/gemma-zaken/standaard/catalogi/ (zoek op "historiemodel")

Is dan de gewenste functionaliteit gewaarborgd? Volgens mij wel nl.

[w-van-weelden]

Hoi @michielverhoef,

Op het eerste gezicht lijkt deze oplossing om een referentie op te vragen op basis van zaaktype-identificatie en datum-geldigheid lost dit probleem op. Je zorgt wel voor weer een extra API-call.

Volgens mij prima om het zo op te lossen! Laten we op basis van de resultaten van project ARA kijken hoe de nieuwe versie van de API's die op een handige manier kunnen ondersteunen. Dank je!

[michielverhoef]

Wellicht is er enige verwarring over versies. De UUID van een zaaktype wijzigt bij een nieuwe versie. En Michiel merkt hier oop dat dit ook de bedoeling is. “Hiermee kan ondubbelzinnig naar de specifieke versie van een resource verwezen worden”. Hier ontstaat verwarring over versies want ik heb het over versies van API’s en Michiel heeft het over versies van resources.

De UUID duidt de resource uniek aan, terwijl de URL de combinatie van API versie en resource uniek aanduidt. Met name voor hergebruik van een ingerichte catalogus is het dan van belang dat de UUID’s gelijk blijven. Dat is volgens mij de kern van dit issue. Zouden jullie daar nog op willen reageren?

Goed om te beseffen is dat een UUID de versie van een zaaktype etc. aanduidt. Wanneer vaan een zaaktype verschillende versies bestaan zijn dit aparte resources die allemaal een eigen UUID (en dus url) hebben.

De resource Zaaktype (en Roltype, Informatieobjecttype etc.) zijn dus versies van dat Zaaktype en wanneer van een Zaaktype meerdere versies bestaan zijn er dus ook meerdere resources.

[michielverhoef]

Volgens mij prima om het zo op te lossen! Laten we op basis van de resultaten van project ARA kijken hoe de nieuwe versie van de API's die op een handige manier kunnen ondersteunen. Dank je!

Team Asterix en ARA hebben niet zoveel met dit probleem te maken, dit is een issue voor het het historiemodel wat op dit moment geïmplementeerd wordt in de referentie-implementatie.

[michielverhoef]

Als ik nog eens naar de oorspronkelijke vraag kijk is er sprake van verwarring en hopelijk is deze weggenomen in de antwoorden.

Ik sluit dit issue.