Data Filtering, Ordering and Limiting

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:

Filtering - Narrow down results based on conditions
Ordering - Sort the filtered results
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):

GET /api/{mockApiId}?filters=status=active&role=user
# Server will interpret as : filters="status=active" and role="user" (separate parameters)

✅ Correct (URL-encoded):

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:

# Raw filter string
filters=status=active

# URL-encoded request
GET /api/{mockApiId}?filters=status%3Dactive

Case-insensitive matching:

# 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):

# Raw filter string
filters=status=active&role=admin

# URL-encoded request
GET /api/{mockApiId}?filters=status%3Dactive%26role%3Dadmin

Not equals:

# Raw filter string
filters=status[$ne]=archived

# URL-encoded request
GET /api/{mockApiId}?filters=status%5B%24ne%5D%3Darchived

Nested field filtering:

# 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

GET /api/{mockApiId}?order_by=createdAt&order_direction=desc

Examples

Ascending order (default):

GET /api/{mockApiId}?order_by=name

Descending order:

GET /api/{mockApiId}?order_by=age&order_direction=desc

Sort nested fields:

GET /api/{mockApiId}?order_by=profile.firstName&order_direction=asc

Limiting

Restrict the number of results returned using the limit parameter.

Syntax

GET /api/{mockApiId}?limit=10

Examples

Get first 5 results:

GET /api/{mockApiId}?limit=5

No limit (return all):

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

# 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:

Filter for records where status is “active” AND role is “user”
Sort by createdAt in descending order
Return only the first 3 results

Example usage

Sample Dataset

This dataset demonstrates both simple fields and nested object structures:

[
  {
    "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

# Raw filter string
filters=status=active&role=user

# URL-encoded request
GET /api/{mockApiId}?filters=status%3Dactive%26role%3Duser

Result:

[
  {
    "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

GET /api/{mockApiId}?order_by=age&order_direction=desc

Result:

[
  {
    "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

# Raw filter string
filters=status=active

# URL-encoded request
GET /api/{mockApiId}?filters=status%3Dactive

Result:

[
  {
    "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

# Raw filter string
filters=email[$eqi]=charlie@example.com

# URL-encoded request
GET /api/{mockApiId}?filters=email%5B%24eqi%5D%3Dcharlie%40example.com

Result:

[
  {
    "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

# Raw filter string
filters=role[$ne]=admin

# URL-encoded request
GET /api/{mockApiId}?filters=role%5B%24ne%5D%3Dadmin

Result:

[
  {
    "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)

# Raw filter string
filters=profile.address.country=USA

# URL-encoded request
GET /api/{mockApiId}?filters=profile.address.country%3DUSA

Result:

[
  {
    "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)

GET /api/{mockApiId}?order_by=profile.firstName&order_direction=asc&limit=3

Result:

[
  {
    "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:

GET /api/{mockApiId}?filters=age[$gt]=30
# Error: Unsupported operator: $gt

Invalid limit:

GET /api/{mockApiId}?limit=-5
# Error: limit must be >= 0

Missing URL encoding (common mistake):

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

Documentation Index

​Overview

​Query Parameters

​URL Encoding

​Why URL Encoding is Required

​Encoding Examples

​Common Character Encodings

​Filtering

​Supported Operators

​Filter Syntax

​Filter Examples

​Ordering

​Syntax

​Examples

​Limiting

​Syntax

​Examples

​Combining Operations

​Example Request

​Example usage

​Sample Dataset

​Query Examples & Results

​Limitations & Conditions

​Error Examples

​Tips & Best Practices

Overview

Query Parameters

URL Encoding

Why URL Encoding is Required

Encoding Examples

Common Character Encodings

Filtering

Supported Operators

Filter Syntax

Filter Examples

Ordering

Syntax

Examples

Limiting

Syntax

Examples

Combining Operations

Example Request

Example usage

Sample Dataset

Query Examples & Results

Limitations & Conditions

Error Examples

Tips & Best Practices