0.33 change: limiteren endpoints

Context

Een aantal API endpoints kunnen gebruikt worden om lijsten van dossiers op te halen. Om te vemrijden dat de stabiliteit en performantie van het eLy-platform geïmpacteerd wordt, worden hier limitaties op gezet.

Beschrijving van de wijzigingen

We beperken het aantal resultaten dat per endpoint in één API call kan opgehaald worden. Het beperken van het aantal simultane calls per integrator (API client) zal in een latere story worden voorzien.

Het beperken van het aantal gelijktijdig opgehaalde resultaten kan op twee manieren gebeuren, afhankelijke van de use case van het API endpoint:

• Ofwel door paginatie te voorzien, zodat een grote resultset in meerdere kleinere sets moet opgehaald worden

• Ofwel door een limiet te voorzien, zodat de request moet aangepast worden (bijvoorbeeld een kleinere zoekrange meegeven) om een aantal resultaten onder de limiet terug te geven.

Wijzigingen bij paginatie

Voor paginatie van een endpoint worden volgende elementen toegevoegd:

• Request

  • pagina : optioneel paginanummer, om een specifieke pagina op te vragen (default eerste pagina)

• Response

  • huidigePagina : paginanummer waarvoor de resultaten in het antwoord teruggeven worden

  • totaalAantalPaginas: totaal aantal pagina’s met resultaten (= totaal aantal requests nodig om alles op te vragen)

  • totaalAantalElementen: geeft het totale aantal dossiers weer voor de gegeven request parameters over alle pagina’s heen

Het toevoegen van deze elementen wijzigt de structuur van het antwoord (niet backwards compatible), de array [] van resultaten wordt een object met een geneste array {[]}. Het gewijzigde endpoint zal daarom als v2 beschikbaar gesteld worden.

• Het originele endpoint in v1 blijft nog gedurende een overgangsperiode beschikbaar tot 24 december 2025.

Wijzigingen bij limitering zonder paginatie

Voor limitering van een endpoint worden volgende elementen toegevoegd:

• Request

  • Geen wijzigingen

• Response

  • Indien het aantal resultaten <= limiet: HTTP 200(geen wijzigingen aan de inhoud)

  • Indien het aantal resultaten > limiet: HTTP 400 met foutcode TEVEEL_RESULTATEN (ook toevoegen in https://athumi.atlassian.net/wiki/spaces/DAO/pages/112656425). De integrator kan dan een nieuwe request lanceren met aangepaste request parameters die het aantal resultaten meer beperken (tot onder de limiet).

Limitering wijzigt de structuur van het antwoord niet en wordt meteen toegepast op API v1 (backwards compatible).

Burgerlijke stand

/burgerlijke-stand/v2/dossiers

Dit endpoint wordt gepagineerd, vermits het door integratoren gebruikt wordt om de volledige set van dossiers voor een gemeente te synchroniseren.

• Paginagrootte wordt ingesteld op 100.

Sortering van de resultaten op dossiernummer.

burgerlijke-stand/v2/verslagen-beedigd-arts

Dit endpoint wordt gepagineerd, vermits er in theorie een grote set resultaten kan bestaan voor een gemeente.

• Paginagrootte wordt ingesteld op 100.

Sortering van de resultaten op datum indiening.

Uitvaartsector

/uitvaart/v2/dossiers

Dit endpoint wordt gepagineerd, maar omdat de data die per dossier wordt teruggeven beperkt is mag het aantal resultaten per pagina vrij groot zijn.

• Paginagrootte wordt ingesteld op 300.

Sortering van de resultaten op <actie nodig> + naam.

De paginatie wordt nog niet in de GUI (Mijn dossiers) toegepast, omdat de kans heel klein is dat het resultaat groter is dan één pagina. Moest dit toch het geval zijn, dan tonen we een waarschuwing.

Opgelet: er zijn teveel openstaande dossiers, enkel de eerste 300 worden getoond. Gelieve behandelde dossiers te sluiten.

/uitvaart/v1/overlijdens

Dit endpoint wordt gelimiteerd vermits het altijd mogelijk is om meer beperkende zoekcriteria in te geven.

• Limiet wordt ingesteld op 100.

De GUI wordt aangepast om een waarschuwing te tonen bij overschrijden van de limiet:

Opgelet: er werden teveel resultaten gevonden, gelieve uw zoekopdracht te verfijnen.

Gemeenten van begraven en crematoria

/begraafplaats/v1/toestemmingen is al gepagineerd

/crematorium/v1/toestemmingen is al gepagineerd

Datadeling

/datadeling/v1/vaststellingen is al gepagineerd