search

melsk-r / HC-BRK-bevragen-issues

0 stars 0 forks source link

Kunnen de descriptions voor query parameters (beter) in een feature worden beschreven? #84

Open melsk-r opened 1 week ago

melsk-r commented 1 week ago

Originally created by CathyDingemanse (https://github.com/VNG-Realisatie/Haal-Centraal-BRK-bevragen/issues/366):

zodat de descriptions korter worden.

[beschrijf de impediment]

[assign aan ..., voeg label 'impediment' toe, kies bij 'projects' voor "organisatie en impediments"]

melsk-r commented 1 week ago

This comment originally might have been created by someone else.

Het doel van die descriptions lijkt mij om de consumer-developer snel van de plek te helpen. Volgens mij waren de features met name om provider-functionaliteit te beschrijven. Ik kan niet goed afwegen wat voor de developer belangrijker is. Korte descriptions met een duidelijke uitleg op een andere plek, of direct de uitleg beschikbaar, maar dan wel in een langere description.

melsk-r commented 1 week ago

This comment originally might have been created by someone else.

Melvin zoekt uit wat de beste optie is. Eventueel ook examples hierin betrekken.

melsk-r commented 1 week ago

This comment originally might have been created by someone else.

Ik heb geprobeerd in een feature te beschrijven hoe 'kadastraal onroerende zaken zoeken' moet werken. Zie: https://github.com/VNG-Realisatie/Haal-Centraal-BRK-bevragen/blob/docs/kadastraal-onroerende-zaken-zoeken/features/kadastraal-onroerende-zaken-zoeken.feature. Ik heb hierdoor igv één zoek pad gevonden die niet werkt zoals beschreven in de OAS, namelijk zoeken op adres kenmerken. Volgens de OAS is alleen postcode verplicht, maar zonder huisnummer krijg ik altijd een 404.

melsk-r commented 1 week ago

This comment originally might have been created by someone else.

@MelvLee zeg je hiermee ook dat je liever de werking van de API voor gebruikers uitlegt in een feature (waarnaar je verwijst) dan in de API specificaties (yaml)?

melsk-r commented 1 week ago

This comment originally might have been created by someone else.

Ik zou niet én de specificatie én alle documentatie in één yaml bestand proberen te stoppen. Ik denk dat een compacte description handig is als een soort reminder. Maar om complexe functionaliteit (zoals alle zoek mogelijkheden/combinaties) te snappen heb ik zeker uitgebreidere documentatie nodig

MelvLee commented 1 week ago

This comment originally might have been created by someone else.

@MelvLee zeg je hiermee ook dat je liever de werking van de API voor gebruikers uitlegt in een feature (waarnaar je verwijst) dan in de API specificaties (yaml)?

Het is naar mijn mening niet voldoende om de API alleen te beschrijven met OAS. Als er ook nog domein specifieke termen zoals kadastraal onroerende zaak als resource namen wordt gebruikt, dan is het zeker handig om dit soort termen uit te leggen en een OAS specificatie is naar mijn mening niet de plek. Als een API ook nog iets met de data doet ipv alleen maar doorkoppen wat in de achterliggende database staat, zoals het samenstellen van adresregels uit adresgegevens, dan is het zeker handig om het algoritme en de uitzonderingen in het algoritme te documenteren. Een voorbeeld om dat te doen is met scenarios. Dan kunnen vragen van consumers ook door (functioneel) beheerders en support medewerkers worden beantwoord (die meestal toegang hebben tot productie data) in plaats van samen met developers omdat die meestal geen toegang hebben tot productie data