Filtering

The NOÉ API filtering system allows applying advanced filters on LIST endpoints using a syntax inspired by MongoDB.

📋 Overview

Filtering works on all LIST endpoints of the API using the filter parameter in the URL.

⚠️ Limitations

Related Objects (ObjectId)

Only ObjectIds can be filtered for references. Properties of related objects are not accessible.

• ✅ Valid: filter={"category":"507f1f77bcf86cd799439011"}
• ❌ Invalid: filter={"category.name":"Accueil"}
• ❌ Invalid: filter={"user.email":"@gmail.com"}

Filterable Field Types

Field Type	Example	Filterable
Direct fields	name, email, createdAt	✅ Yes
ObjectId references	category, user, activity	✅ By ID only
Properties of related objects	category.name, user.email	❌ No
Custom fields	customFields.field1	✅ Yes

🚀 Supported Endpoints

All LIST endpoints support filtering.

Projects

• GET /projects - Projects
• GET /projects/public - Public projects

Per Project

• GET /projects/:projectId/activities - Activities
• GET /projects/:projectId/categories - Categories
• GET /projects/:projectId/places - Spaces
• GET /projects/:projectId/sessions - Sessions
• GET /projects/:projectId/stewards - Supervisors
• GET /projects/:projectId/teams - Teams
• GET /projects/:projectId/registrations - Registrations

📖 Syntax and Examples

You must use a JSON format directly in the URL:

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

🔧 Supported Operators

Operator	Description	Example
$eq	Equal to	filter={"name":{"$eq":"Atelier"}}
$ne	Not equal to	filter={"status":{"$ne":"cancelled"}}
$gt	Greater than	filter={"age":{"$gt":18}}
$gte	Greater than or equal	filter={"age":{"$gte":18}}
$lt	Less than	filter={"price":{"$lt":100}}
$lte	Less than or equal	filter={"price":{"$lte":100}}
$in	Contained in the array	filter={"status":{"$in":["active","pending"]}}
$nin	Not contained in the array	filter={"status":{"$nin":["cancelled","archived"]}}
$regex	Regular expression	filter={"name":{"$regex":"^ate"}}
$options	Regex options	filter={"name":{"$regex":"workshop","$options":"i"}}
$exists	Field exists	filter={"description":{"$exists":true}}
$all	Contains all values	filter={"tags":{"$all":["music","art"]}}
$size	Array size	filter={"slots":{"$size":3}}

🔄 Filter Combination

Multiple filters can be combined in the same request:

# Simple combination
GET /projects/:projectId/activities?filter={"active":true,"name":{"$regex":"atelier"}}

# Complex combination
GET /projects/:projectId/sessions?filter={"start":{"$gte":"2024-01-01"},"end":{"$lt":"2024-12-31"}}

📅 Date Format

Dates must be in ISO 8601 format:

# Full format
GET /projects/:projectId/sessions?filter={"start":{"$gte":"2024-01-01T00:00:00.000Z"}}

# Simple date format
GET /projects/:projectId/sessions?filter={"start":{"$gte":"2024-01-01"}}
GET /projects/:projectId/sessions?filter={"start":{"$gte":"2024"}}

🎯 Examples by Entity Type

Activities

# Activities by name
GET /projects/:projectId/activities?filter={"name":{"$regex":"atelier","$options":"i"}}

# Activities by category (ID)
GET /projects/:projectId/activities?filter={"category":"507f1f77bcf86cd799439011"}

# Activities with specific tags
GET /projects/:projectId/activities?filter={"tags":{"$in":["musique","art"]}}

Sessions

# Sessions by name
GET /projects/:projectId/sessions?filter={"name":{"$regex":"matin"}}

# Sessions by activity (ID)
GET /projects/:projectId/sessions?filter={"activity":"507f1f77bcf86cd799439011"}

# Sessions after a date
GET /projects/:projectId/sessions?filter={"start":{"$gte":"2024-01-01"}}

Registrations

# Registrations by role
GET /projects/:projectId/registrations?filter={"role":"admin"}

# Registrations by user (ID)
GET /projects/:projectId/registrations?filter={"user":"507f1f77bcf86cd799439011"}

# Registrations subscribed to a certain session (ID)
GET /projects/:projectId/registrations?filter={"sessionsSubscriptions.session": "68dacf51c55364e0b89d45ce"

# Registrations created after a date
GET /projects/:projectId/registrations?filter={"createdAt":{"$gte":"2024-01-01"}}

# Registrations by steward (ID)
GET /projects/:projectId/registrations?filter={"steward":"507f1f77bcf86cd799439011"}

Spaces

# Spaces by capacity
GET /projects/:projectId/places?filter={"maxNumberOfParticipants":{"$gte":50}}

# Spaces by name
GET /projects/:projectId/places?filter={"name":{"$regex":"bar"}}

🛡️ Security and Limitations

Blocked Operators

The following dangerous operators are blocked for security reasons:

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

Limitations

• Maximum regex pattern length: 500 characters
• Maximum array size: 100 elements
• Strict parameter validation before execution