Interrogation

Tous les endpoints de liste de l’API prennent en charge un ensemble commun de paramètres de requête pour la Pagination, le tri et le filtrage.

Paramètres communs

Paramètre	Type	Description
`page`	`number`	Numéro de page à récupérer (par défaut : 1).
`limit`	`number`	Nombre d’éléments à récupérer par page (par défaut : 10).
`sort`	`string`	Champ utilisé pour le tri. Préfixe `-` pour l’ordre décroissant (ex. `-createdAt`).
`where`	`object`	Objet de requête pour filtrer les résultats à l’aide d’opérateurs.

Réponse de Pagination

Tous les endpoints de liste renvoient une Réponse paginée avec la structure suivante :


{
  "docs": [...],
  "totalDocs": number,
  "limit": number,
  "totalPages": number,
  "page": number,
  "pagingCounter": number,
  "hasPrevPage": boolean,
  "hasNextPage": boolean,
  "prevPage": number | null,
  "nextPage": number | null
}

Tri

Utilise le paramètre de requête sort pour ordonner les résultats selon un champ précis.

Ordre de tri

Croissant (par défaut) : ?sort=createdAt
Décroissant : préfixe - → ?sort=-createdAt

Champs triables

Tu peux trier selon n’importe quel champ de premier niveau de l’objet. Exemples courants :

Champ	Description
`createdAt`	Trier par date de création
`updatedAt`	Trier par date de dernière modification
`title`	Trier par ordre alphabétique sur le titre

Exemples

Du plus récent au plus ancien :


?sort=-createdAt

Du plus ancien au plus récent :


?sort=createdAt

Par ordre alphabétique sur le titre :


?sort=title

Opérateurs where

Le paramètre de requête where accepte un objet de requête qui permet de filtrer les résultats avec différents opérateurs :

Opérateur	Description
`equals`	La valeur doit être exactement égale.
`not_equals`	Renvoie tous les documents dont la valeur n’est pas égale.
`greater_than`	Pour champs numériques ou basés sur une date.
`greater_than_equal`	Pour champs numériques ou basés sur une date.
`less_than`	Pour champs numériques ou basés sur une date.
`less_than_equal`	Pour champs numériques ou basés sur une date.
`like`	Chaîne insensible à la casse qui doit être présente. S’il s’agit d’une chaîne de mots, tous les mots doivent être présents, dans n’importe quel ordre.
`contains`	Doit contenir la valeur saisie, sans tenir compte de la casse.
`in`	La valeur doit figurer dans la liste de valeurs fournie, séparées par des virgules.
`not_in`	La valeur ne doit PAS figurer dans la liste de valeurs fournie, séparées par des virgules.
`exists`	Ne renvoie que les documents où la valeur existe (`true`) ou n’existe pas (`false`).

Logique ET / OU

Tu peux combiner plusieurs requêtes avec une logique and / or. Tu peux les imbriquer autant que nécessaire pour construire des requêtes complexes.

Exemples de requête

Filtrer par valeur exacte :


?where[status][equals]=COMPLETE

Filtrer lorsque la valeur contient une chaîne :


?where[title][contains]=tutorial

Filtrer par date (strictement supérieure) :


?where[createdAt][greater_than]=2024-01-01

Filtrer lorsqu’un champ existe :


?where[description][exists]=true

Avec une logique OR :


?where[or][0][status][equals]=COMPLETE&where[or][1][status][equals]=PROCESSING

Avec une logique AND :


?where[and][0][status][equals]=COMPLETE&where[and][1][visibility][equals]=private

Utilisation du package qs

Les requêtes complexes deviennent vite difficiles à écrire en chaînes de paramètres de requête. Nous recommandons d’utiliser le package qs-esm pour convertir des objets JSON en chaînes de paramètres de requête :


import { stringify } from 'qs-esm';
 
const query = stringify({
  where: {
    status: {
      equals: 'COMPLETE'
    },
    and: [
      { visibility: { equals: 'private' } },
      { createdAt: { greater_than: '2024-01-01' } }
    ]
  },
  limit: 20,
  page: 1
}, { addQueryPrefix: true });
 
// Result: ?where[status][equals]=COMPLETE&where[and][0][visibility][equals]=private&where[and][1][createdAt][greater_than]=2024-01-01&limit=20&page=1

Cette approche facilite grandement la construction et la maintenance de requêtes complexes par programmation.