api-pagination-filtering-sortinglisted

Standardize HTTP query parameter conventions and response metadata for paginated, filtered, and sorted list endpoints. ## When to use - Designing a new list endpoint with pagination, filtering, or sorting - Implementing multi-value or hierarchical filters (e.g., segment, family, class filters) - Building repository/query builder layers that translate query params to SQL - Adding search across multiple fields to a list endpoint - Standardizing response metadata across paginated endpoints - Reviewing endpoint consistency for pagination patterns - Adding sort_by/order_by capabilities to existing endpoints - Implementing cursor-based pagination for large datasets (complement to offset-based) ## Core conventions 1. **Pagination styles**: Two common patterns emerge—(a) `page` (1-indexed) + `page_size` with `total_pages` in response; (b) `limit` + `offset` (0-indexed) with `has_next` boolean. Pattern (a) is friendlier for UI pagination controls; pattern (b) is more SQL-native. Choose one per service; mixing within a service confuses clients. `page_size` or `limit` should have a `ge=1, le=<MAX>` constraint (common max: 100 or 1000). 2. **Offset calculation**: When using `page`/`page_size`, calculate `offset = (page - 1) * page_size` in the route handler or service layer before passing to repository. When using `limit`/`offset`, pass directly. Both approaches translate to `LIMIT {limit} OFFSET {offset}` in SQL. 3. **Response pagination metadata**: Standardize on a `PaginationInf