Advanced request matching

You can match resources to requests using attributes such as the HTTP method, path, query string, headers or body. For JSON and XML request bodies, JsonPath and XPath can also be used, respectively.

Match operators

Matchers support a number of operators to control how the match is performed.

For example:

resources:
- method: GET
  path: /example
  requestHeaders:
    content-type:
      value: somevalue
      operator: Contains
  response:
    statusCode: 400

The following operators are supported:

Operator	Description
`EqualTo`	Checks if the expression result equals the `value`.
`NotEqualTo`	Checks if the expression result does not equal the `value`.
`Exists`	Checks if the expression result is not `null` or absent.
`NotExists`	Checks if the expression result is `null` or absent.
`Contains`	Checks if the expression result contains the `value`.
`NotContains`	Checks if the expression result does not contain the `value`.
`Matches`	Checks if the expression result matches the regular expression specified in the `value` field.
`NotMatches`	Checks if the expression result does not match the regular expression specified in the `value` field.

Note If no operator is specified, then EqualTo is used.

Matching against HTTP method, path, query string or headers

See Configuration for simple matching against HTTP method, path, query string or headers.

If you need more complex matching, you can use the 'long form' configuration, which allows you to specify a match expression and operator for each attribute.

For example:

resources:
- method: GET
  path: /example
  requestHeaders:
    content-type:
      value: somevalue
      operator: Contains
  response:
    statusCode: 400

Request matchers support the range of operators described in this document.

Matching against the request body

You can also match a resource based on the request body. For JSON and XML request bodies, JsonPath and XPath can also be used, respectively.

Matching a JSON request body

You can match a resource based on a JsonPath query of a JSON request body.

Only JSON request bodies are supported for the feature.

Specify the match configuration using the requestBody.jsonPath property of a resource.

Here you specify a JsonPath expression, and the value it must match.

For example:

resources:
- method: GET
  path: /example1
  requestBody:
    jsonPath: $.foo
    value: bar
  response:
    statusCode: 204

This example will match a request body like this:

{ "foo": "bar" }

Any of the match operators, such as Contains, Matches etc. can be used in a JsonPath matcher.

Unmatched or null JsonPath expressions

If the result of evaluating the JsonPath expression is null or if the path evaluates to non-existent property in the body, then it is considered null.

You can explicitly match a null value, as follows:

resources:
- method: GET
  path: /example2
  requestBody:
    jsonPath: $.not-matching-example
    value: null
  response:
    statusCode: 409

Note: the YAML keyword null indicates a null value, not the string literal "null"

Matching an XML request body

You can match a resource based on a XPath query of a XML request body.

Only XML request bodies are supported for the feature.

Specify the match configuration using the requestBody.xPath property of a resource.

Here you specify a XPath expression, relevant namespaces, and the value it must match.

For example:

resources:
- method: GET
  path: /example1
  requestBody:
    xPath: "/env:Envelope/env:Body/pets:animal/pets:name"
    value: "Fluffy"
    xmlNamespaces:
      env: "http://schemas.xmlsoap.org/soap/envelope/"
      pets: "urn:com:example:petstore"
  response:
    statusCode: 204

This example will match a request body like this:

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Header/>
  <env:Body>
    <pets:animal xmlns:pets="urn:com:example:petstore">
      <pets:name>Fluffy</pets:name>
    </pets:animal>
  </env:Body>
</env:Envelope>

Note: although this example uses a SOAP envelope, any valid XML body can be matched.

Reusing XML namespace definitions

Instead of specifying the namespace definitions for each XPath expression, you can define them once at the top level of the configuration:

plugin: rest

resources:
- method: GET
  path: /example1
  requestBody:
    xPath: "/env:Envelope/env:Body/pets:animal/pets:name"
    value: "Fluffy"
  response:
    statusCode: 204

- method: GET
  path: /example2
  requestBody:
    xPath: "/env:Envelope/env:Body/pets:animal/pets:name"
    value: "Paws"
  response:
    statusCode: 400

# XML namespaces shared by all XPath expressions
system:
  xmlNamespaces:
    env: "http://schemas.xmlsoap.org/soap/envelope/"
    pets: "urn:com:example:petstore"

Any of the match operators, such as Contains, Matches etc. can be used in an XPath matcher.

Unmatched or null XPath expressions

If the result of evaluating the XPath expression is null or if the path evaluates to non-existent property in the body, then it is considered null.

You can explicitly match a null value, as follows:

resources:
- method: GET
  path: /example-nonmatch
  requestBody:
    xPath: "/env:Envelope/env:Body/pets:animal/pets:nothing"
    # tilde is YAML for null
    value: ~
    xmlNamespaces:
      env: "http://schemas.xmlsoap.org/soap/envelope/"
      pets: "urn:com:example:petstore"
  response:
    statusCode: 409

Note: the YAML keyword null indicates a null value, not the string literal "null"

Matching raw request body content

You can match a resource based on the raw content of the request body.

Specify the match configuration using the requestBody.operator and requestBody.value properties of a resource.

Here you specify the operator and a value to compare.

For example:

resources:
- method: GET
  path: /example1
  requestBody:
    operator: EqualTo
    value: bar
  response:
    statusCode: 204

This example will match a request body like this:

bar

Any of the match operators, such as Contains, Matches etc. can be used in a request body matcher.

Matching an empty request body

If the request body is empty, then it is considered null.

You can explicitly match a null value, as follows:

resources:
- method: GET
  path: /example2
  requestBody:
    operator: EqualTo
    value: null
  response:
    statusCode: 409

Note: the YAML keyword null indicates a null value, not the string literal "null"

Using multiple request body matchers

You can use multiple request body matchers for a resource. Using the allOf or anyOf conditions controls how the matchers are combined.

All matchers must match

resources:
- method: GET
  path: /example1
  requestBody:
    allOf:
    - jsonPath: $.foo
      value: bar
    - jsonPath: $.baz
      value: qux
  response:
    statusCode: 204

At least one matcher must match

resources:
- method: GET
  path: /example1
  requestBody:
    anyOf:
    - jsonPath: $.foo
      value: bar
    - jsonPath: $.baz
      value: qux
  response:
    statusCode: 204

Body match operators

Body matchers support the range of operators described in this document.

For example:

resources:
- method: GET
  path: /example1
  requestBody:
    jsonPath: $.foo
    value: bar
    operator: NotEqualTo
  response:
    statusCode: 400

Note If no operator is specified, then EqualTo is used.

Matching using expressions

You can match resources using expressions, using the template syntax. This provides a powerful way to match against request attributes (including headers, path parameters, query parameters, or body content) as well as store items (including the request store).

Using allOf expressions

Use the allOf property when all expressions must evaluate to true for the resource to be matched.

For example:

resources:
- method: POST
  path: /example
  allOf:
    - expression: "${context.request.headers.Authorization}"
      operator: Matches
      value: "Bearer .*"
    - expression: "${context.request.headers.X-API-Version}"
      operator: EqualTo
      value: "2024-01"
  response:
    statusCode: 204

This example will match a request with both headers:

Authorization: Bearer abc123
X-API-Version: 2024-01

Using anyOf expressions

Use the anyOf property when at least one expression must evaluate to true for the resource to be matched.

For example:

resources:
- method: POST
  path: /example
  anyOf:
    - expression: "${context.request.headers.X-Legacy-Auth}"
      operator: EqualTo
      value: "legacy-token"
    - expression: "${context.request.headers.Authorization}"
      operator: Matches
      value: "Bearer .*"
  response:
    statusCode: 204

This example will match a request with either header:

X-Legacy-Auth: legacy-token

or:

Authorization: Bearer abc123

Using match operators

Any of the match operators, such as Contains and Matches, can be used in an expression matcher. If no operator is specified, EqualTo is used by default.

For example, using the Contains operator:

resources:
- method: POST
  path: /example
  allOf:
    - expression: "${context.request.headers.X-Test}"
      operator: Contains
      value: "test"
  response:
    content: "Header contains test"

Or using a regular expression with the Matches operator:

resources:
- method: POST
  path: /example
  allOf:
    - expression: "${context.request.headers.X-Test}"
      operator: Matches
      value: "test-.*"
  response:
    content: "Header matches pattern"

Expression syntax

Expressions use the template syntax. See Response templates for details of the available placeholders and syntax.

Common placeholders include:

${context.request.headers.HEADER_NAME} - Access request headers
${context.request.pathParams.PARAM_NAME} - Access path parameters
${context.request.queryParams.PARAM_NAME} - Access query parameters
${context.request.body} - Access the raw request body
${context.request.path} - Access the request path
${context.request.uri} - Access the full request URI
${stores.request.someKey} - Access a value stored in the request store
${stores.example.someKey} - Access a value stored in the example store

Directory-based responses

See Directory-based responses for a way to serve files from a directory based on the incoming request path.

Resource matching performance

Resource matching is typically the fastest method of providing conditional responses. This is the case for request properties such as headers, query parameters, path parameters, path and HTTP method. In the case of using JsonPath or XPath to query the request body to conditionally match resources, however, the body must be parsed, which is computationally expensive and will result in lower performance.