Filtrage

Le système de filtrage de l'API NOÉ permet d'appliquer des filtres complexes sur les endpoints LIST en utilisant une syntaxe inspirée de MongoDB.

📋 Vue d'ensemble

Le filtrage fonctionne sur tous les endpoints LIST de l'API en utilisant le paramètre filter dans l'URL.

⚠️ Limitations

Objets liés (ObjectId)

Lors du filtrage sur des objets liés, vous ne pouvez filtrer que par leur ObjectId, pas par leurs propriétés.

• ✅ Filtre valide : filter[category]=507f1f77bcf86cd799439011
• ❌ Filtre invalide : filter[category.name]=Accueil
• ❌ Filtre invalide : filter[user.email]=@gmail.com

Types de champs filtrables

Type de champ	Exemple	Filtrable
Champs directs	name, email, createdAt	✅ Oui
ObjectId références	category, user, activity	✅ Par ID uniquement
Propriétés d'objets liés	category.name, user.email	❌ Non
Champs personnalisés	customFields.field1	✅ Oui

🚀 Endpoints supportés

Tous les endpoints LIST supportent le filtrage :

Projets

• GET /projects - Projets
• GET /projects/public - Projets publics

Par projet

• GET /projects/:projectId/activities - Activités
• GET /projects/:projectId/categories - Catégories
• GET /projects/:projectId/places - Espaces
• GET /projects/:projectId/sessions - Sessions
• GET /projects/:projectId/stewards - Responsables
• GET /projects/:projectId/teams - Équipes
• GET /projects/:projectId/registrations - Inscriptions

📖 Syntaxe et exemples

Format JSON

Vous pouvez utiliser un format JSON directement dans l'URL :

GET /projects/:projectId/activities?filter={"name":{"$regex":"atelier","$options":"i"},"tags":{"$in":["musique","art"]}}

tip

Le format JSON est souvent plus lisible et moins sujet aux erreurs d'encodage.

Format Query Params

1. Filtre simple (égalité exacte)

GET /projects/:projectId/activities?filter[name]=Atelier

2. Opérateurs de comparaison

# Supérieur à
GET /projects/:projectId/sessions?filter[maxNumberOfParticipants][$gt]=10

# Inférieur ou égal
GET /projects/:projectId/registrations?filter[createdAt][$lte]=2024-01-01

# Différent de
GET /projects/:projectId/activities?filter[status][$ne]=cancelled

3. Recherche textuelle

# Recherche insensible à la casse
GET /projects/:projectId/activities?filter[name][$regex]=atelier&filter[name][$options]=i

# Recherche partielle
GET /projects/:projectId/places?filter[name][$regex]=salle

4. Opérations sur tableaux

# Contient l'une des valeurs
GET /projects/:projectId/activities?filter[tags][$in]=musique,art,danse

# Ne contient aucune des valeurs
GET /projects/:projectId/registrations?filter[role][$nin]=admin,contributeur

# Contient toutes les valeurs
GET /projects/:projectId/activities?filter[tags][$all]=musique,art

# Taille du tableau
GET /projects/:projectId/sessions?filter[slots][$size]=3

🔧 Opérateurs supportés

Opérateur	Description	Exemple
$eq	Égal à	filter[name][$eq]=Atelier
$ne	Différent de	filter[status][$ne]=annulé
$gt	Supérieur à	filter[age][$gt]=18
$gte	Supérieur ou égal	filter[age][$gte]=18
$lt	Inférieur à	filter[prix][$lt]=100
$lte	Inférieur ou égal	filter[prix][$lte]=100
$in	Dans le tableau	filter[statut][$in]=actif,en_attente
$nin	Pas dans le tableau	filter[statut][$nin]=annulé,archivé
$regex	Expression régulière	filter[nom][$regex]=^ate
$options	Options regex	filter[nom][$options]=i
$exists	Champ existe	filter[description][$exists]=true
$all	Contient toutes les valeurs	filter[tags][$all]=musique,art
$size	Taille du tableau	filter[créneaux][$size]=3

🔄 Combinaison de filtres

Plusieurs filtres peuvent être combinés dans une même requête :

# Combinaison simple
GET /projects/:projectId/activities?filter[active]=true&filter[name][$regex]=atelier

# Combinaison complexe (format JSON)
GET /projects/:projectId/sessions?filter={\"start\":{\"$gte\":\"2024-01-01\"},\"end\":{\"$lt\":\"2024-12-31\"}}

📅 Format des dates

Les dates doivent être au format ISO 8601 :

# Format complet
GET /projects/:projectId/sessions?filter[start][$gte]=2024-01-01t00:00:00.000Z

# Format date simple
GET /projects/:projectId/sessions?filter[start][$gte]=2024-01-01

🎯 Exemples par type d'entité

Activités

# Toutes les activités actives
GET /projects/:projectId/activities?filter[active]=true

# Activités par catégorie (ID)
GET /projects/:projectId/activities?filter[category]=507f1f77bcf86cd799439011

# Recherche par nom
GET /projects/:projectId/activities?filter[name][$regex]=atelier&filter[name][$options]=i

# Activités avec tags spécifiques
GET /projects/:projectId/activities?filter[tags][$in]=musique,art

Sessions

# Sessions futures
GET /projects/:projectId/sessions?filter[start][$gte]=2024-01-01

# Sessions par activité (ID)
GET /projects/:projectId/sessions?filter[activity]=507f1f77bcf86cd799439011

# Sessions avec places disponibles
GET /projects/:projectId/sessions?filter[numberParticipants][$lt]=filter[maxNumberOfParticipants]

# Sessions par nom
GET /projects/:projectId/sessions?filter[name][$regex]=matin

Inscriptions

# Inscriptions par rôle
GET /projects/:projectId/registrations?filter[role]=participant

# Inscriptions par utilisateur (ID)
GET /projects/:projectId/registrations?filter[user]=507f1f77bcf86cd799439011

# Inscriptions créées après une date
GET /projects/:projectId/registrations?filter[createdAt][$gte]=2024-01-01

# Inscriptions par responsable (ID)
GET /projects/:projectId/registrations?filter[steward]=507f1f77bcf86cd799439011

Espaces

# Espaces par capacité
GET /projects/:projectId/places?filter[maxNumberOfParticipants][$gte]=50

# Recherche par nom
GET /projects/:projectId/places?filter[name][$regex]=salle

🛡️ Sécurité et limitations

Opérateurs bloqués

Les opérateurs dangereux suivants sont bloqués pour des raisons de sécurité :

• $where
• $near
• $geoWithin
• $geoIntersects

Limitations

• Longueur maximale des patterns regex : 500 caractères
• Taille maximale des tableaux : 100 éléments
• Validation stricte des paramètres avant exécution