Toevoeging aan Design decisions n.a.v. BAG#265?

[melsk-r]

Originally created by melsk-r (https://github.com/VNG-Realisatie/Haal-Centraal-common/issues/72):

HaalCentraal BAG issue 265 en het daarmee samenhangende #44 gaat over de interpretatie/implementatie van de 'field' parameter op het moment dat er in een resource, in de _links en/of in een groep een property voorkomt met dezelfde naam. In de API strategie is uitgelegd hoe deze functionaliteit geïmplementeerd moet worden. In #44 wordt echter een nuancering aangebracht die leidt tot een toevoeging in de functionaliteit zonder dat deze in tegenspraak is met de betreffende paragraaf in de API strategie.

Ik vraag me af of die toevoeging niet in de Design Decision moet worden vermeldt. Overigens gaat het hier n.m.m. niet echt om een Design Decision en is het dus de vraag waar het na invoering van #27 moet worden ondergebracht.

[melsk-r]

This comment originally might have been created by someone else.

van mij hoeft het niet in de design decisions, het is immers al vastgelegd in een feature

[melsk-r]

This comment originally might have been created by someone else.

Begrijp ik maar is het niet goed om API ontwerpers voor te houden dat dit een optie is om in overweging te nemen?

[melsk-r]

This comment originally might have been created by someone else.

Ik ben het met Frank eens. Met de Features beschrijven we aanvullende functionaliteit. Anders moeten we elke feature in de Design Decisions gaan opnemen.

[melsk-r]

This comment originally might have been created by someone else.

Je zou in design decisions kunnen opnemen wanneer we wel of niet fields opnemen (bijna altijd). En wanneer expand, en hoe (opnemen in description wat expand kan worden). Ook overwegingen voor het opnemen van paginering. Wanneer welke responses (foutcodes) moeten worden opgenomen. Wanneer acceptCRS en contentCrs (request) en contentCrs (response) headers moeten worden opgenomen. Enz. Maar hoe die functionaliteit werkt voor gebruikers hoort denk ik echt niet in de design decisions (ontwerprichtlijnen)

[melsk-r]

This comment originally might have been created by someone else.

Ik dacht dat je in een design decision document beschrijft waarom je afwijkt van de standaard. In dit geval volgen we de API strategie niet en volgens mij is het dan handig om te weten (herhaling van de resource naam) waarom er is afgeweken. De hoe kan dan zoals Frank aangeeft in een ander document (feature file) worden beschreven.

Ik heb zelf zitten rondzoeken om te kijken hoe anderen dit hebben geïmplementeerd en ik kwam een mogelijk interessante oplossing tegen: https://www.gcloud.belgium.be/rest/#document-consult

[melsk-r]

This comment originally might have been created by someone else.

Ik dacht dat je in een design decision document beschrijft waarom je afwijkt van de standaard.

Mee eens, alleen hebben we hier in de "design decisions" ontwerprichtlijnen beschreven. Ik stel voor om het document dan ook "ontwerprichtlijnen" te noemen, en zo nodig echte ontwerpbeslissingen (besloten afwijkingen van de standaard) te documenteren in design decisions.

Ik ben nog niet overtuigd dat we afwijken van de API strategie. Waar en hoe staat in de API strategie dat dit niet mag?

Ik lees alleen maar "The query parameter accepts a comma-separated list of field names." Er staat niks over gegevens in groepen en het gebruik van de dot-notatie. Eigenlijk is gebruik van de dot-notatie in strijd met de API strategie, wanneer je de API strategie leest alsof het de bijbel is en je niet tot de rekkelijken behoort. Dus als je wilt verwijzen naar een afwijking op de API strategie, dan moet gebruik van de dot-notatie afwijzen. Tja... Onze fields feature is dus m.i. een uitbreiding op de API strategie, maar niet in tegenspraak.

[melsk-r]

This comment originally might have been created by someone else.

Akkoord om hem niet op te nemen in de Design Decisions. We gaan hem in de API Kennisbank echter wel opnemen als Implementatie overweging in een apart daarvoor te creëren document.