Comment fonctionne la pagination

L'API GraphQL de Legalesign utilise la pagination basée sur les curseurs selon la spécification de connexion Relay. Chaque liste d'éléments — documents, modèles, contacts, factures — utilise ce même schéma.

Le modèle de connexion

La terminologie vient de la théorie des graphes — les nœuds sont des points, les arêtes sont des lignes qui les relient. Dans l'API, une arête décrit la relation entre deux types et peut porter des métadonnées supplémentaires (comme les permissions qu'un User a dans un Group).

Lorsque vous interrogez une liste, vous n'obtenez pas un tableau simple. Vous obtenez un objet connexion composé de trois parties :

documentConnection(first: 20) {
  documents { ... }     # the items (shortcut)
  totalCount            # total matching items
  pageInfo {            # pagination cursors
    startCursor
    endCursor
    hasNextPage
    hasPreviousPage
  }
}

Pourquoi pas simplement un tableau ?

La pagination basée sur les curseurs est stable. Contrairement à la pagination par décalage (page=2), les curseurs ne cassent pas lorsque des éléments sont ajoutés ou supprimés entre les requêtes. Cela est important lorsque les documents sont envoyés et signés en temps réel.

Récupérer la première page

Utilisez first pour limiter les résultats. Lors de la pagination d'un ensemble complet de résultats dans l'ordre de création, passez "0" ou "START" comme argument after lors de votre premier appel pour indiquer que vous commencez une séquence paginée :

query {
  group(id: "grpYourGroupId") {
    documentConnection(first: 100, after: "0") {
      documents {
        id
        name
        status
        created
      }
      pageInfo {
        endCursor
        hasNextPage
      }
      totalCount
    }
  }
}

Récupérer la page suivante

Si hasNextPage est true, passez endCursor comme argument after :

query {
  group(id: "grpYourGroupId") {
    documentConnection(first: 100, after: "eyJpZCI6ImRvYzEyMyJ9") {
      documents {
        id
        name
        status
        created
      }
      pageInfo {
        endCursor
        hasNextPage
      }
      totalCount
    }
  }
}

Répétez jusqu'à ce que hasNextPage soit false.

Arguments de pagination

Toutes les connexions acceptent ces arguments :

Argument	Type	Description
first	Int	Nombre d'éléments à retourner depuis le début
after	ID	Curseur après lequel commencer (pour pagination avant)
last	Int	Nombre d'éléments à retourner depuis la fin
before	ID	Curseur avant lequel commencer (pour pagination arrière)

La plupart des connexions acceptent également des arguments de filtre spécifiques au type de données. Par exemple, documentConnection accepte from, to, status, search, sendType et sender.

Le raccourci des arêtes

Les connexions fournissent à la fois edges (avec curseur par élément) et une liste raccourcie. Pour la plupart des cas d'usage, le raccourci est plus simple :

# Shortcut — simpler, no per-item cursor
documentConnection(first: 20) {
  documents {
    id
    name
  }
  pageInfo {
    endCursor
    hasNextPage
  }
}

# Full edges — needed if you want per-item cursors
documentConnection(first: 20) {
  edges {
    node {
      id
      name
    }
    cursor
  }
  pageInfo {
    endCursor
    hasNextPage
  }
}

Utilisez le raccourci sauf si vous avez besoin des curseurs individuels (par ex. pour supprimer un élément spécifique et reprendre à ce point).

remarque

totalCount retourne le nombre pour la page actuelle, pas le total sur toutes les pages. Le coût de calcul d'un total global sur potentiellement des millions d'enregistrements rend un total réel impraticable.

Exemple concret

Voici comment l'application Console de Legalesign pagine les documents avec un défilement infini via TanStack Query :

query queryInfiniteDocuments {
  group(id: "grpYourGroupId") {
    documentConnection(
      first: 100
      after: "eyJpZCI6ImRvYzEyMyJ9"
      sendType: SINGLE
      from: "2025-01-01T00:00:00Z"
      to: "2025-06-01T00:00:00Z"
    ) {
      documents {
        id
        name
        status
        senderName
        created
        recipients {
          id
          email
          status
          signedDateTime
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
      totalCount
    }
  }
}

L'application récupère la première page, puis au défilement utilise endCursor comme after pour charger le lot suivant.

Quels types utilisent des connexions ?

Chaque relation de liste dans l'API utilise ce modèle :

• Group.documentConnection, templateConnection, batchConnection, contactConnection, experienceConnection, scheduleConnection, attachmentConnection, memberConnection, invitationConnection, standardMessageConnection, contactGroupConnection, draftConnection, activityConnection
• Organisation.groupConnection, dataStopConnection, dataDeletionConnection, retentionConnection, userConnection, invoiceConnection, dataSubjectConnection
• Batch.documentConnection
• Billing.invoiceConnection
• Invoice.lineItemConnection
• Template.elementConnection, userSignatureConnection
• Document.elementConnection
• Recipient.elementConnection
• User.memberConnection, organisationConnection, supportTicketConnection