RFC24069 Pagination aan GraphQL schema toevoegen

[rvanrest]

eDocs volgnummer

No response

Korte probleem omschrijving

Wanneer het resultaat van een query groot is (veel data, lijsten) is het met de huidige specificatie niet mogelijk om deze vooraf te beperken. Dit heeft gevolgen voor performance (veel data ophalen en over de lijn) en de raadpleger heeft er geen controle over.

Korte omschrijving voorgestelde oplossing

Pagination toevoegen.

Deze techniek maakt het mogelijk om grote resultaat datasets op te splitsen in beheersbare delen of pagina's.

RFC gevolgen voor het onderdeel/de onderdelen

Koppelvlak specificatie, Autorisatie (policy/query)

Welk ander onderdeel?

No response

Betrokken partij RFC

Zorginstituut

Andere betrokken partij

No response

Indiener RFC

Zorginstituut

Andere organisatie / contactpersoon

VECOZO

Analyse - Waarom pagineren

Door het toevoegen van pagination krijgt de raadpleger controle over het de hoeveelheid op te vragen data. Vooral wanneer er veel data wordt verwacht geeft dit voordelen voor performance en voorspelde resultaten. De data kan op basis van gebruikersinput opgeknipt worden in 'pages'.

Belangrijke redenen om paginering aan je GraphQL-implementatie toe te voegen:

1. Verbeterde Prestatie en Efficiëntie

• Verminderde Serverbelasting: Door slechts een subset van gegevens op te halen in plaats van een volledige dataset, wordt de belasting op de server verminderd. Dit voorkomt dat je server overbelast raakt door grote dataverzoeken, wat vooral belangrijk is voor applicaties met veel gebruikers of met grote hoeveelheden data.
• Snellere Reactietijden: Door alleen de benodigde gegevens op te halen, worden de responsietijden van je GraphQL-API aanzienlijk verbeterd. Dit leidt tot een snellere en soepelere ervaring voor de eindgebruiker.

2. Geoptimaliseerd Geheugen- en Netwerkgebruik

• Lagere Geheugengebruik: Het ophalen van een kleiner aantal records betekent dat er minder geheugen wordt gebruikt, zowel op de server als op de client. Dit is vooral belangrijk voor clients met beperkte middelen, zoals mobiele apparaten.
• Minder Netwerkverkeer: Door alleen de nodige gegevens te versturen, wordt het netwerkverkeer verminderd. Dit is vooral belangrijk voor mobiele applicaties of andere situaties waarin de bandbreedte beperkt is.

3. Betere Gebruikerservaring

• Geleidelijke Data-ophaal: Paginering stelt je in staat om gegevens geleidelijk te laden naarmate de gebruiker verder scrolt of specifieke pagina's opvraagt. Dit voorkomt dat gebruikers lange wachttijden ervaren terwijl een grote hoeveelheid data wordt geladen.
• Infinite Scrolling en Paginaweergave: Veel moderne gebruikersinterfaces maken gebruik van "infinite scrolling" of duidelijke paginaweergave om grote hoeveelheden inhoud beheersbaar te maken. Paginering in je GraphQL-implementatie maakt het gemakkelijk om deze UI-patronen te ondersteunen.

4. Betere Controle Over Gegevensstroom

• Fijnmazige Controle Over Dataweergave: Paginering biedt meer controle over hoeveel data wordt weergegeven en hoe het wordt gestructureerd, wat handig is voor verschillende datavisualisaties en weergaven in je applicatie.
• Efficiëntie bij Gegevensverwerking: Voor databases of back-ends die gegevens in stukken verwerken, helpt paginering om de bewerkingen efficiënter uit te voeren en om lange, tijdrovende zoekopdrachten te vermijden.

5. Beheer van Veranderlijke Data

• Consistentie bij Dynamische Gegevens: Cursor-gebaseerde paginering helpt om consistentie te behouden wanneer de onderliggende gegevens veranderen tussen verschillende fetches (zoals bij dynamische content updates). Dit voorkomt dat gebruikers dubbele gegevens zien of dat gegevens worden overgeslagen.

6. Schaalbaarheid

• Voorbereiding op Toekomstige Groei: Als je applicatie groeit en meer gebruikers en data aankan, wordt paginering essentieel om schaalbaarheid te waarborgen. Door je API van meet af aan te optimaliseren voor paginering, maak je je systeem klaar voor toekomstige groei zonder ingrijpende herstructureringen.

7. Compliantie en Beveiliging

• Beveiliging tegen Overbelasting: Door een limiet in te stellen op het aantal items dat kan worden opgevraagd, kun je je server beschermen tegen potentieel schadelijke queries die een zeer grote dataset proberen op te halen. Dit verbetert de veiligheid en stabiliteit van je API.
• Datagovernance: Door paginering kun je beter voldoen aan datagovernancebeleid, zoals het beperken van het delen van gevoelige informatie door alleen de noodzakelijke gegevens op te halen.

Methoden voor paginering in GraphQL

Er zijn twee meest voorkomende methoden:

• offset-gebaseerde paginering
• cursor-gebaseerde paginering

Hoewel offset-gebaseerde paginering van de twee de eenvoudigst te implementeren methode is, is de meest gebruikte methode de cursor-gebaseerde paginering. Op basis van een startregel (offset) en een aantal (limit) worden er vanaf de startregel het aantal opgegeven regels teruggegeven.

De belangrijkste argumenten tegen offset-gebaseerde paginering zijn dat de server bij een groot aantal records de volledige data moet raadplegen om het startpunt te vinden en dat er bij mutaties (verwijderen/toevoegen) in de onderliggende data het resultaat onvoorspelbaar maakt.

Cursor-gebaseerde paginering is efficiënter en betrouwbaarder. In plaats van een offset te gebruiken, wordt een unieke identificatie (cursor) gebruikt die naar een specifieke locatie in de dataset wijst. Deze methode is sneller en zorgt voor consistentie tussen verzoeken, zelfs als de gegevens veranderen.

Relay Pagination is een methode die gebruik maakt van cursor-gebaseerde paginering om efficiënt met grote datasets om te gaan en dynamische gegevensveranderingen te ondersteunen.

Relay Paginering in GraphQL

Relay maakt gebruik van een specifiek patroon voor het omgaan met paginering, bekend als het Connection en Edge model. Dit model definieert hoe de paginering moet worden uitgevoerd en welke velden moeten worden gebruikt.

Connection Model

Het Connection model in Relay introduceert twee belangrijke concepten:

1. Edges: Dit vertegenwoordigt de verbindingen tussen nodes (datapunten) en bevat de data (node) en de cursor (cursor) die aangeeft waar in de lijst de data zich bevindt.
2. PageInfo: Dit is een object dat metadata bevat over de paginering, zoals of er meer pagina's zijn om op te halen (hasNextPage) en wat de cursor van het laatste item in de huidige pagina is (endCursor).

Voorbeeld van een Relay-paginering in GraphQL-query:

    query {
      users(first: 5, after: "cursor123") {
        edges {
          node {
            id
            name
          }
          cursor
        }

        pageInfo {
          endCursor
          hasNextPage
        }
      }
    }

Velden in Relay Paginering

• first: Geeft aan hoeveel items je wilt ophalen, vanaf de gegeven cursor.
• after: De cursor die aangeeft vanaf welk punt de query moet beginnen met het ophalen van gegevens.
• edges: Bevat een lijst van verbindingen tussen nodes, elk met een node (de daadwerkelijke data) en een cursor.
• node: Dit is de daadwerkelijke data die door de query wordt opgevraagd.
• cursor: Een unieke identificatie die aangeeft waar deze node zich in de dataset bevindt.
• pageInfo: Bevat informatie over de paginering, zoals hasNextPage (of er nog meer data is) en endCursor (de cursor van het laatste item in de lijst).

Voorbeeld van Relay Paginering GraphQL-schema:

type Query {
  users(first: Int, after: String): UserConnection
}

type UserConnection {
  edges: [UserEdge]
  pageInfo: PageInfo
}

type UserEdge {
  node: User
  cursor: String
}

type PageInfo {
  hasNextPage: Boolean
  endCursor: String
}

type User {
  id: ID
  name: String
}

In dit schema:

• UserConnection definieert de connectie met een lijst van gebruikers (edges) en de metadata voor paginering (pageInfo).
• UserEdge is een individuele verbinding naar een User node met een cursor.
• PageInfo geeft informatie over de paginering, zoals of er nog meer items beschikbaar zijn en de cursor voor het ophalen van de volgende set gegevens.

Wijzigingsvoorstel

Op dit moment is er geen concrete noodzaak om paginering toe te passen in het Netwerkmodel iWlz. De huidige query-specificaties gaan altijd uit van het opvragen via één specifiek ID waaraan een beperkt aantal records teruggegeven zal worden.

Maar met de NVS in gedachten blijft dit hoogstwaarschijnlijk niet de enige wijze waarop data geraadpleegd zal worden en zullen er ook grotere datasets opgevraagd worden met meer records als resultaat. Dan is paginering een waardevolle toevoeging aan de GraphQL implementatie.

Paginering maakt nu nog geen onderdeel uit van de GraphQL implementatie van het Netwerkmodel iWlz. Voor het toevoegen van paginering zullen de huidige GraphQL-specificaties maar waarschijnlijk ook de geimplementeerde resolvers aangepast moeten worden. Server en client moeten paginering ook ondersteunen.

Maar omdat het gebruik van GraphQL nu nog beperkt is, is de aanpassing ook ook voor een beperkte groep.

Het voorstel is daarom om paginering bij de eerste mogelijkheid toe te voegen aan de GraphQL implmentatie van het Netwerkmodel iWlz om de impact van deze wijziging kleiner te houden dan wanneer het volledig iWlz ketenlandschap en met de recente ontwikkeling om het netwerkmodel breder in te zetten dan het domein iWlz, zelfs daarbuiten.

Gezien het gedrag in de datasets die als dynamische gecategoriseerd kunnen worden is het voorstel om Cursor-Based Pagination toe te passen en specifiek de [Relay-techniek]()

Meer informatie:

• [GraphQL Cursor Connections specification](https://relay.dev/graphql/connections.htm

Uitwerking wijzigingsvoorstel per onderdeel

ERD

geen wijzigingen

Regels

mogelijk regels of afspraken opstellen voor cursor-type en limit

Proces

geen wijzigingen

Gegevens

geen functionele, wel technische (zie koppelvlak)

Koppelvlak

De huidige GraphQL koppelvlakken moeten aangepast worden voor paginering.

Overige

Geschikt maken Server en Client.

Overweging wijzigingsvoorstel(len)

Oplossing	Voordeel / Nadeel	Overweging
1. ..	Voordeel:
	Nadeel:
#. Niets doen	Voordeel: geen wijziging nodig
	Nadeel: probleem blijft aanwezig

...

Conclusie

None

Gekozen oplossing

No response

Publicatiemoment

No response

Implementatiemoment

No response