Pagination dans l’API

Définition

La pagination est une technique pour diviser une grande quantité de données en plusieurs pages. Cela améliore les performances et offre une meilleure expérience utilisateur en limitant la quantité de données transférées et affichées à un moment donné.

OnlineERP peut, dans certains cas où les données seraient trop volumineuses et risqueraient d’endommager les systèmes, paginer vos données.

Portez attention!

Avantages du Retour Paginé

1. Performance améliorée
   • Requêtes plus rapides et utilisation réduite des ressources serveur.
2. Expérience utilisateur
   • Navigation simplifiée pour éviter de submerger les utilisateurs avec un trop-plein de données.
3. Gestion de la mémoire
   • Charge moins lourde sur la mémoire en ne renvoyant qu’une portion des données à la fois.

Structure d’un Retour Paginé

Le format d’un retour paginé inclut les éléments suivants :

• Data : Liste des résultats pour la page actuelle.
• ResultsCount : Nombre d’éléments dans la page actuelle.
• TotalCount : Nombre total d’éléments dans la collection complète.
• Skipped : Nombre d’éléments ignorés avant la page actuelle.
• Top : Nombre d’éléments renvoyés dans la page actuelle.

Exemple de réponse paginée :

Faire une requête paginée

Voici un exemple de requête paginée pour récupérer les produits via un URI /entity/products :

Requête HTTP :

Explication des paramètres :

• skip=20 : Ignore les 20 premiers résultats (page 3 si on affiche 10 éléments par page).
• top=10 : Renvoie un maximum de 10 éléments pour cette requête.
• ALLOW_PAGINATION: true (en-tête) : Indique que la pagination est activée et que la réponse sera structurée en conséquence. Si vous omettez ce paramètre, le retour sera donc une liste normale (mais paginée! voir plus bas).

Activer ou non la Pagination

• Header requis pour activer la pagination : Inclure l’en-tête ALLOW_PAGINATION dans la requête.
  • Format paginé : Le retour suivra la structure ci-dessus.
  • Format dépaginé : Une simple liste de résultats sera renvoyée.

  Cas particuliers

  Certains endpoints peuvent forcer la pagination (ex. : récupération des produits).

  • Si le header ALLOW_PAGINATION est absent, vous obtiendrez uniquement une partie des résultats.
  • Vérifiez les headers de retour pour détecter si une pagination a été appliquée.

  En-têtes de retour pour la Pagination

  Que le retour soit paginé ou dépaginé, les informations suivantes seront incluses dans les headers de réponse :s

  • X-Pagination-ResultsCount : Nombre de résultats dans la page actuelle.
  • X-Pagination-TotalCount : Nombre total d’éléments dans la collection.
  • X-Pagination-Skipped : Nombre d’éléments ignorés avant cette page.
  • X-Pagination-Top : Nombre maximal d’éléments à renvoyer.

  Détection d’une Pagination

  Pour savoir si une pagination a été appliquée :

  • Si l’en-tête X-Pagination-Top est NULL ou vide, aucune pagination n’a été effectuée.