Request Matching Filters (Advanced)

When building or testing APIs, developers often need mock servers that can respond intelligently to different kinds of HTTP requests. Beeceptor’s Request Matching Filters, in rules engine, provide this flexibility by allowing you to define precise matching conditions.

These filters determine how Beeceptor selects a matching mock rule when multiple rules exist for the same endpoint. Instead of relying solely on simple attributes like request path, method, or headers, Beeceptor enables you to match based on complex request characteristics like SOAPMethod, GraphQL query or deeply nested values.

Body Parameter Matching

The Body Parameter Matching Operator is ideal for REST APIs that send structured data in the request body. Rather than matching on raw text, Beeceptor can parse the body and match on individual parameters enabling you to match requests with nested fields, arrays, and multiple content types.

Supported Content Types & Operators

Beeceptor extracts body parameters from the incoming requests and parses in structured data. This feature supports specific content types such as application/json and others, allowing parameters to be accessed and compared using dot notation for nested structures.

Content Type	Description
JSON	Parses and supports nested access using dot notation, e.g., user.profile.email.
Form URL-encoded	Parses application/x-www-form-urlencoded data into key-value pairs.
Multipart Form Data	Extracts text fields from multipart requests (file uploads are ignored).

Once the request body is parsed, Beeceptor extracts parameter values using dot notation, which follows a string-based path similar to JSON’s property access pattern. This approach simplifies working with deeply nested data structures, even when intermediate properties may or may not exist. Refer to the example below to see how this works.

Beeceptor supports the following comparison operators for common data types, including strings, numbers, booleans, and arrays.

Operator	Description
Equals (=)	Exact type-aware match.
Not Equals (≠)	Negation of equals.
Contains (∈)	Checks if the value contains the target (applies to arrays, objects, and strings).
Doesn't Contain (∉)	Negation of contains.
Is Null (∅)	Checks if the parameter is null.
Is Not Null (¬∅)	Checks if the parameter exists and has any value.

Example Request

Let’s say your mock server receives the following JSON request from a REST API.

{
  "user": {
    "id": 123,
    "email": "david@example.com",
    "role": "admin",
    "preferences": {
      "theme": "dark",
      "notifications": true
    }
  },
  "items": [
    {"name": "item1", "quantity": 2},
    {"name": "item2", "quantity": 1}
  ]
}

Example Matching Rules

You can apply the filters below using dot notation to accurately match and compare values within nested objects.

Example Filter in Mock Rule	Description
user.email Equals david@example.com	Matches when user email equals the given value.
user.role Contains admin	Matches if the user’s role includes admin.
items[0].name Equals "item1"	Matches first item’s name.
user.preferences.theme Not Equals "light"	Matches if theme is not “light”.
items.length Equals 2	Matches if the items array has two items

SOAPAction Matching

The SOAPAction Matching is designed for handling SOAP (Simple Object Access Protocol) web service requests. In SOAP APIs, the SOAPAction header or WS-Addressing field identifies the exact operation being invoked (e.g., getUser, createOrder, etc.). Beeceptor can use this information to direct such requests to the correct mock behavior.

How It Works

When a SOAP request arrives, Beeceptor attempts to extract the action identifier using a prioritized detection process:

1. Content-Type Header: Extracts the action from the action parameter within the Content-Type header. Example: Content-Type: application/soap+xml; action="http://example.org/getUser"
2. SOAPAction Header: Uses the SOAPAction HTTP header, removing quotes if present. Example: SOAPAction: "http://example.org/orders/getUser"
3. WS-Addressing: If WS-Addressing is used, Beeceptor parses the Action element from the SOAP message body.
4. SOAP Body Operation: As a last resort, Beeceptor parses the operation name directly from the SOAP body XML.

Example Usage

POST /soap-endpoint
SOAPAction: http://example.org/orders/getUser
Content-Type: application/xml

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getUser xmlns="http://example.org/users">
      <Name>Atharva</Name>
      <Age>23</Age>
    </getUser>
  </soap:Body>
</soap:Envelope>

In the above example, you can define a rule in Beeceptor that matches the SOAPAction http://example.org/orders/getUser and returns the corresponding mock SOAP response.

GraphQL Query Matching

The GraphQL Query Matching helps you create rules that specifically match GraphQL operations such as queries, mutations, or subscriptions. Since the GraphQL client sends most requests to a single endpoint (e.g., /graphql), matching based on the query name or structure is essential.

How It Works

Beeceptor extracts the GraphQL query text using the following order of precedence:

1. Request Body Field: Extracts from the query field inside the request's JSON body.
2. Query Parameter (Fallback): If the query is not found in the body, Beeceptor checks the query parameter in the URL.

Example Usage

POST /graphql
Content-Type: application/json

{
  "query": "query GetUser { user(id: \"123\") { id name email } }",
  "variables": null
}

In this case, you create a mock rule that matches the GetUser operation or looks for a specific pattern inside the query string.

Example usage in mock rule:

query GetUser {
  user(id: "123") {
    id
    name
    email
  }
}