> ## Documentation Index > Fetch the complete documentation index at: https://docs.mocklyapi.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Data Filtering, Ordering and Limiting > MocklyAPI gives you the ability to filter, order and limit data from your mock endpoints ## Overview MocklyAPI provides powerful query capabilities for JSON array responses. You can filter, sort, and limit your mock data using URL query parameters. **Operations are applied in this order:** 1. **Filtering** - Narrow down results based on conditions 2. **Ordering** - Sort the filtered results 3. **Limiting** - Restrict the number of results returned These operations only work when your mock data is a **JSON array**. Single objects or non-JSON responses will be returned as-is. *** ## Query Parameters | Parameter | Type | Description | | ----------------- | ------ | ----------------------------------------------------- | | `filters` | string | URL-encoded filter conditions (supports nested paths) | | `order_by` | string | Field name to sort by (supports nested paths) | | `order_direction` | string | Sort direction: `asc` or `desc` (default: `asc`) | | `limit` | number | Maximum number of results to return (minimum: 0) | ## URL Encoding **The `filters` parameter must be URL-encoded** when it contains special characters like `=`, `&`, `[`, `]`. ### Why URL Encoding is Required When you include multiple filter conditions, the `&` character needs to be encoded as `%26` to prevent it from being interpreted as a query parameter separator. ### Encoding Examples **❌ Incorrect (will only apply first filter):** ```bash theme={null} GET /api/{mockApiId}?filters=status=active&role=user # Server will interpret as : filters="status=active" and role="user" (separate parameters) ``` **✅ Correct (URL-encoded):** ```bash theme={null} GET /api/{mockApiId}?filters=status%3Dactive%26role%3Duser # Server will interpret as : filters="status=active&role=user" (single parameter) ``` ### Common Character Encodings | Character | URL Encoded | Usage | | --------- | ----------- | -------------------------- | | `=` | `%3D` | Equality operator | | `&` | `%26` | Filter condition separator | | `[` | `%5B` | Operator start bracket | | `]` | `%5D` | Operator end bracket | | `:` | `%3A` | Used in nested paths | ## Filtering Apply conditions to narrow down your results using the `filters` query parameter. ### Supported Operators | Operator | Description | Case Sensitive | | ------------ | ----------------------------- | -------------- | | `$eq` | Equals | Yes | | `$eqi` | Equals (case-insensitive) | No | | `$ne` | Not equals | Yes | | `$nei` | Not equals (case-insensitive) | No | | *(implicit)* | Direct equality (no operator) | Yes | ### Filter Syntax Filters use query string format and support: * Simple equality: `filters=status=active` * Operators: `filters=status[$eq]=active` * Multiple conditions (AND logic): `filters=status=active&role=admin` * Nested fields: `filters=user.name=John` ### Filter Examples **Simple equality:** ```bash theme={null} # Raw filter string filters=status=active # URL-encoded request GET /api/{mockApiId}?filters=status%3Dactive ``` **Case-insensitive matching:** ```bash theme={null} # Raw filter string filters=email[$eqi]=JOHN@EXAMPLE.COM # URL-encoded request GET /api/{mockApiId}?filters=email%5B%24eqi%5D%3DJOHN%40EXAMPLE.COM ``` **Multiple conditions (AND):** ```bash theme={null} # Raw filter string filters=status=active&role=admin # URL-encoded request GET /api/{mockApiId}?filters=status%3Dactive%26role%3Dadmin ``` **Not equals:** ```bash theme={null} # Raw filter string filters=status[$ne]=archived # URL-encoded request GET /api/{mockApiId}?filters=status%5B%24ne%5D%3Darchived ``` **Nested field filtering:** ```bash theme={null} # Raw filter string filters=profile.address.country=USA # URL-encoded request GET /api/{mockApiId}?filters=profile.address.country%3DUSA ``` *** ## Ordering Sort your results by any field using `order_by` and `order_direction` parameters. ### Syntax ```bash theme={null} GET /api/{mockApiId}?order_by=createdAt&order_direction=desc ``` ### Examples **Ascending order (default):** ```bash theme={null} GET /api/{mockApiId}?order_by=name ``` **Descending order:** ```bash theme={null} GET /api/{mockApiId}?order_by=age&order_direction=desc ``` **Sort nested fields:** ```bash theme={null} GET /api/{mockApiId}?order_by=profile.firstName&order_direction=asc ``` *** ## Limiting Restrict the number of results returned using the `limit` parameter. ### Syntax ```bash theme={null} GET /api/{mockApiId}?limit=10 ``` ### Examples **Get first 5 results:** ```bash theme={null} GET /api/{mockApiId}?limit=5 ``` **No limit (return all):** ```bash theme={null} GET /api/{mockApiId} ``` The limit is applied **after** filtering and ordering. Set `limit=0` to return an empty array. *** ## Combining Operations You can combine filtering, ordering, and limiting in a single request. ### Example Request ```bash theme={null} # Raw filter string filters=status=active&role=user&order_by=createdAt&order_direction=desc&limit=3 # Complete URL-encoded request GET /api/{mockApiId}?filters=status%3Dactive%26role%3Duser&order_by=createdAt&order_direction=desc&limit=3 ``` This will: 1. Filter for records where `status` is "active" AND `role` is "user" 2. Sort by `createdAt` in descending order 3. Return only the first 3 results *** ## Example usage ### Sample Dataset This dataset demonstrates both simple fields and nested object structures: ```json theme={null} [ { "id": 1, "username": "alice_admin", "email": "alice@example.com", "status": "active", "role": "admin", "age": 32, "createdAt": "2024-01-15", "profile": { "firstName": "Alice", "lastName": "Johnson", "address": { "city": "New York", "country": "USA", "zipCode": "10001" } } }, { "id": 2, "username": "bob_user", "email": "bob@example.com", "status": "active", "role": "user", "age": 28, "createdAt": "2024-02-20", "profile": { "firstName": "Bob", "lastName": "Smith", "address": { "city": "London", "country": "UK", "zipCode": "SW1A 1AA" } } }, { "id": 3, "username": "charlie_inactive", "email": "CHARLIE@EXAMPLE.COM", "status": "inactive", "role": "user", "age": 45, "createdAt": "2024-01-10", "profile": { "firstName": "Charlie", "lastName": "Brown", "address": { "city": "Paris", "country": "France", "zipCode": "75001" } } }, { "id": 4, "username": "diana_user", "email": "diana@example.com", "status": "active", "role": "user", "age": 35, "createdAt": "2024-03-05", "profile": { "firstName": "Diana", "lastName": "Prince", "address": { "city": "San Francisco", "country": "USA", "zipCode": "94102" } } }, { "id": 5, "username": "eve_admin", "email": "eve@example.com", "status": "active", "role": "admin", "age": 29, "createdAt": "2024-02-28", "profile": { "firstName": "Eve", "lastName": "Adams", "address": { "city": "Toronto", "country": "Canada", "zipCode": "M5H 2N2" } } } ] ``` ### Query Examples & Results **Example 1: Filter active users** ```bash theme={null} # Raw filter string filters=status=active&role=user # URL-encoded request GET /api/{mockApiId}?filters=status%3Dactive%26role%3Duser ``` **Result:** ```json theme={null} [ { "id": 2, "username": "bob_user", "email": "bob@example.com", "status": "active", "role": "user", "age": 28, "createdAt": "2024-02-20", "profile": { "firstName": "Bob", "lastName": "Smith", "address": { "city": "London", "country": "UK", "zipCode": "SW1A 1AA" } } }, { "id": 4, "username": "diana_user", "email": "diana@example.com", "status": "active", "role": "user", "age": 35, "createdAt": "2024-03-05", "profile": { "firstName": "Diana", "lastName": "Prince", "address": { "city": "San Francisco", "country": "USA", "zipCode": "94102" } } } ] ``` *** **Example 2: Order by age descending** ```bash theme={null} GET /api/{mockApiId}?order_by=age&order_direction=desc ``` **Result:** ```json theme={null} [ { "id": 3, "username": "charlie_inactive", "email": "CHARLIE@EXAMPLE.COM", "status": "inactive", "role": "user", "age": 45, "createdAt": "2024-01-10", "profile": { "firstName": "Charlie", "lastName": "Brown", "address": { "city": "Paris", "country": "France", "zipCode": "75001" } } }, { "id": 4, "username": "diana_user", "email": "diana@example.com", "status": "active", "role": "user", "age": 35, "createdAt": "2024-03-05", "profile": { "firstName": "Diana", "lastName": "Prince", "address": { "city": "San Francisco", "country": "USA", "zipCode": "94102" } } }, { "id": 1, "username": "alice_admin", "email": "alice@example.com", "status": "active", "role": "admin", "age": 32, "createdAt": "2024-01-15", "profile": { "firstName": "Alice", "lastName": "Johnson", "address": { "city": "New York", "country": "USA", "zipCode": "10001" } } }, { "id": 5, "username": "eve_admin", "email": "eve@example.com", "status": "active", "role": "admin", "age": 29, "createdAt": "2024-02-28", "profile": { "firstName": "Eve", "lastName": "Adams", "address": { "city": "Toronto", "country": "Canada", "zipCode": "M5H 2N2" } } }, { "id": 2, "username": "bob_user", "email": "bob@example.com", "status": "active", "role": "user", "age": 28, "createdAt": "2024-02-20", "profile": { "firstName": "Bob", "lastName": "Smith", "address": { "city": "London", "country": "UK", "zipCode": "SW1A 1AA" } } } ] ``` *** **Example 3: Active users, newest first, limit 2** ```bash theme={null} # Raw filter string filters=status=active # URL-encoded request GET /api/{mockApiId}?filters=status%3Dactive ``` **Result:** ```json theme={null} [ { "id": 4, "username": "diana_user", "email": "diana@example.com", "status": "active", "role": "user", "age": 35, "createdAt": "2024-03-05", "profile": { "firstName": "Diana", "lastName": "Prince", "address": { "city": "San Francisco", "country": "USA", "zipCode": "94102" } } }, { "id": 5, "username": "eve_admin", "email": "eve@example.com", "status": "active", "role": "admin", "age": 29, "createdAt": "2024-02-28", "profile": { "firstName": "Eve", "lastName": "Adams", "address": { "city": "Toronto", "country": "Canada", "zipCode": "M5H 2N2" } } } ] ``` *** **Example 4: Case-insensitive email search** ```bash theme={null} # Raw filter string filters=email[$eqi]=charlie@example.com # URL-encoded request GET /api/{mockApiId}?filters=email%5B%24eqi%5D%3Dcharlie%40example.com ``` **Result:** ```json theme={null} [ { "id": 3, "username": "charlie_inactive", "email": "CHARLIE@EXAMPLE.COM", "status": "inactive", "role": "user", "age": 45, "createdAt": "2024-01-10", "profile": { "firstName": "Charlie", "lastName": "Brown", "address": { "city": "Paris", "country": "France", "zipCode": "75001" } } } ] ``` *** **Example 5: Exclude admins, youngest first** ```bash theme={null} # Raw filter string filters=role[$ne]=admin # URL-encoded request GET /api/{mockApiId}?filters=role%5B%24ne%5D%3Dadmin ``` **Result:** ```json theme={null} [ { "id": 2, "username": "bob_user", "email": "bob@example.com", "status": "active", "role": "user", "age": 28, "createdAt": "2024-02-20", "profile": { "firstName": "Bob", "lastName": "Smith", "address": { "city": "London", "country": "UK", "zipCode": "SW1A 1AA" } } }, { "id": 4, "username": "diana_user", "email": "diana@example.com", "status": "active", "role": "user", "age": 35, "createdAt": "2024-03-05", "profile": { "firstName": "Diana", "lastName": "Prince", "address": { "city": "San Francisco", "country": "USA", "zipCode": "94102" } } }, { "id": 3, "username": "charlie_inactive", "email": "CHARLIE@EXAMPLE.COM", "status": "inactive", "role": "user", "age": 45, "createdAt": "2024-01-10", "profile": { "firstName": "Charlie", "lastName": "Brown", "address": { "city": "Paris", "country": "France", "zipCode": "75001" } } } ] ``` *** **Example 6: Filter by nested country (USA)** ```bash theme={null} # Raw filter string filters=profile.address.country=USA # URL-encoded request GET /api/{mockApiId}?filters=profile.address.country%3DUSA ``` **Result:** ```json theme={null} [ { "id": 1, "username": "alice_admin", "email": "alice@example.com", "status": "active", "role": "admin", "age": 32, "createdAt": "2024-01-15", "profile": { "firstName": "Alice", "lastName": "Johnson", "address": { "city": "New York", "country": "USA", "zipCode": "10001" } } }, { "id": 4, "username": "diana_user", "email": "diana@example.com", "status": "active", "role": "user", "age": 35, "createdAt": "2024-03-05", "profile": { "firstName": "Diana", "lastName": "Prince", "address": { "city": "San Francisco", "country": "USA", "zipCode": "94102" } } } ] ``` *** **Example 7: Order by first name ascending (Nested path)** ```bash theme={null} GET /api/{mockApiId}?order_by=profile.firstName&order_direction=asc&limit=3 ``` **Result:** ```json theme={null} [ { "id": 1, "username": "alice_admin", "email": "alice@example.com", "status": "active", "role": "admin", "age": 32, "createdAt": "2024-01-15", "profile": { "firstName": "Alice", "lastName": "Johnson", "address": { "city": "New York", "country": "USA", "zipCode": "10001" } } }, { "id": 2, "username": "bob_user", "email": "bob@example.com", "status": "active", "role": "user", "age": 28, "createdAt": "2024-02-20", "profile": { "firstName": "Bob", "lastName": "Smith", "address": { "city": "London", "country": "UK", "zipCode": "SW1A 1AA" } } }, { "id": 3, "username": "charlie_inactive", "email": "CHARLIE@EXAMPLE.COM", "status": "inactive", "role": "user", "age": 45, "createdAt": "2024-01-10", "profile": { "firstName": "Charlie", "lastName": "Brown", "address": { "city": "Paris", "country": "France", "zipCode": "75001" } } } ] ``` **Nested Path Support:** * Use dot notation to access nested properties at any depth (e.g., `profile.address.city`) * Ordering supports nested paths for both ascending and descending sorts *** ## Limitations & Conditions **Important Constraints:** * **JSON Arrays Only**: Operations only apply to JSON array responses. Single objects are returned unchanged. * **AND Logic**: Multiple filter conditions use AND logic (all must match). OR logic is not supported. * **Supported Operators**: Only `$eq`, `$eqi`, `$ne`, `$nei` are supported. Other operators will result an error. * **Nested Path Support**: Use dot notation for nested fields (e.g., `user.profile.age`) * **URL Encoding Required**: Always URL-encode the `filters` parameter to avoid parsing errors *** ## Error Examples **Unsupported operator:** ```bash theme={null} GET /api/{mockApiId}?filters=age[$gt]=30 # Error: Unsupported operator: $gt ``` **Invalid limit:** ```bash theme={null} GET /api/{mockApiId}?limit=-5 # Error: limit must be >= 0 ``` **Missing URL encoding (common mistake):** ```bash theme={null} GET /api/{mockApiId}?filters=status=active&role=user # Data didn't filtered accurately : Only first filter applied (status=active), role treated as separate parameter ``` *** ## Tips & Best Practices * **Always URL Encode**: Use your programming language's URL encoding function to encode the `filters` parameter * **Test Incrementally**: Test filters, ordering, and limits separately before combining * **Nested Fields**: Take advantage of dot notation for complex data structures * **Performance**: Limiting results can improve response times for large datasets