API ontwikkeling / Architectuur: voeg paginering van collecties artikel toe

[terborg]

Voegt een nieuw architectuurartikel toe over paginering van collecties in REST API's, met een vergelijking van offset-based en cursor-based paginering op het gebied van schaalbaarheid, page skew en willekeurige toegang.

[changeset-bot]

⚠️ No Changeset found

Latest commit: f2a53e0

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[terborg]

@joepio, @joeribekker, zouden jullie dit wellicht willen reviewen?

[TimvdLippe]

FYI @sanderke voor de Pagination Module van de API Design Rules

[tomootes]

@dvh benieuwd naar jouw mening.

[dvh]

"De API hanteert een eigen default en maximum"; deze zou ik dan ook uitdrukken in OAS

[terborg]

Dat is een bewuste ontwerpkeuze (van het voorbeeld :-)). Als we maximum en default vastleggen in de OAS, wordt het contract dichtgetimmerd. Dat heeft nadelen voor backwards compatibility (zelfde consumer, nieuwere provider) of forwards compatibility (nieuwere consumer, zelfde provider):

De (voorbeeld) API is zo ontworpen dat de provider de controle houdt. Als een consumer limit=10000 meestuurt, weigert de provider niet met een foutmelding, maar geeft deze bijvoorbeeld gewoon 100 items terug. Als we maximum: 100 in OAS zetten, en beide partijen hebben een strikte OAS-validatie aanstaan (of er tussenin zitten), dan hebben we al snel een upgrade-hell.

Wat wel een idee zou zijn, is om bijv. de orde-grootte van de default en maximum in de description op te nemen waabij optimale performance verwacht kan worden. Dan blijft het contract flexibel en robuust tegen toekomstige wijzigingen.

[dvh]

Nice! Wellicht kunnen we het opknippen in het stukje over offset vs cursor paginering en welke wanneer te gebruiken en hoe dit in de API terugkomt. Wij gebruiken bijvoorbeeld Link headers om te pagineren, zodat de keuze tussen offset en cursor er voor de consumer niet voor doet; deze hoeft enkel de links te volgen die aanwezig zijn om te kunnen pagineren. Vervolg is dan of je die links in de headers teruggeeft of in de body (of allebei). Weer anderen gebruiken volledige hypermedia responses zoals HAL of JSON API.

Nu kunnen we hier die discussie gaan voeren op dit PR, maar tegelijkertijd wordt er ook gewerkt aan een Pagination module voor ADR waar de discussie eigenlijk thuishoort.

Het stuk over offset vs cursor is generiek; dat kunnen we sowieso snel publiceren. Voor de vorm van die informatie bestaan verschillende smaakjes, die we of allemaal moeten beschrijven of volgens de ADR uitkomsten.

[TimvdLippe]

De pagination module die morgen voor het eerst wordt besproken staat hier: https://github.com/Logius-standaarden/API-mod-pagination Voor concrete suggesties wat hier moet worden opgeschreven, maak gerust een issue aan. Dan kunnen we die meenemen in de discussie morgenochtend.