Adding response rules

After creating multiple responses for each route, you can create more complex scenarios and serve the responses depending on the fulfillment of rules.

 Defining rules

You can define an unlimited number of rules for each route. At each request, Mockoon will assert each response's rules and serve the response which contains the first matching rule(s). The rules are interpreted in the order they are declared: [rule OR|AND rule] OR [rule OR|AND rule], the brackets symbolizing each route response.

To add a new rule to a response, go to the route response's Rules tab, click on "Add rule" and fill the fields:

 Reordering rules

By default, rules are interpreted in the order you added them. You can change their interpretation order by drag and dropping them:

 Disabling rules

You can temporarily disable the rules and serve the default response only. To activate this option, click on the "rules" icon next to the response list:

 Rules logical operator

Inside a route response, rules are interpreted by default with the OR logical operator. When you have more than one rule in a route response, you can easily switch the operator applied when interpreting the rules, by clicking on the OR|AND buttons at the left of the rules:

Rules have five parts:

• a target
• a property name or path
• an invert operator toggle
• a comparison operator
• a value

 1. Target

In the dropdown menu you can choose between:

• the request body value (full raw content or one of its properties if request's Content-Type is either application/json, application/x-www-form-urlencoded, multipart/form-data, application/xml, application/soap+xml or text/xml).
• the value of a request's query parameter.
• the value of a request header.
• the value of a request cookie.
• the value of a route parameter.
• the value of the request path, always starting with a / (e.g. /path/section).
• the value of the request method in lowercase (e.g. get, post, put, delete, patch, head, options).
• the request number index starting at 1 (you can reset the request number by using the state purge admin API).
• the value of a global variable.
• the value of a data bucket content.
• custom templating (see the templating helpers documentation).

 2. Target's name or path, or template

This field supports templating helpers to dynamically target a specific body property, header name, etc. Depending on the target, the way to access properties may be different:

• request body:
  • keep empty to match against the full raw body content.
  • use a path to access one of its properties. Two syntaxes are supported, object-path or JSONPath Plus. When using object-path, properties containing dots are supported by escaping the dots: key.key\.with\.dot. Fetching object properties is compatible with request's bodies of Content-Type application/json, application/x-www-form-urlencoded, multipart/form-data, application/xml, application/soap+xml or text/xml.
    Please note that XML bodies are parsed using xml-js package. Refer to this page or the package documentation for more information on how the XML is parsed and how to fetch specific properties.
    Please also note that multipart/form-data only supports fields. Uploaded files will be ignored.

    📘 Check the supported requests body formats documentation for more information on how the request body is parsed.

• query parameter: either provide a property name like filter or a path if the query parameter is an object filter.primary.

  📘 Check the query parameters documentation for more information on how they are parsed.

• headers: a header name like Accept or Content-Type.
• cookies: the cookie name like Session-id.
• route parameter: a route parameter name without the colon (":"), :userId becoming userId.
• request path: no property or path can be provided here.
• request method: no property or path can be provided here.
• request number: no property or path can be provided here.
• global variable: a global variable name like myVar. You can use a path to access one of its properties if the variable is storing arrays or objects. Two syntaxes are supported, object-path or JSONPath Plus. When using object-path, properties containing dots are supported by escaping the dots: myVar.key\.with\.dot. Examples: myVar.property.subProperty, myVar.property.0.subProperty or $.myVar.property.
• data bucket content: a data bucket name like myData. You can use a path to access one of its properties if the bucket is storing arrays or objects. Two syntaxes are supported, object-path or JSONPath Plus. When using object-path, properties containing dots are supported by escaping the dots: myData.key\.with\.dot. Examples: myData.property.subProperty, myData.property.0.subProperty or $.myData.property.
• custom templating: custom templating helpers like {{urlParam 'param'}}, {{header 'x-custom-header'}}, {{body 'property'}}, {{jwtPayload (header 'Authorization') 'sub'}}, etc. The result of the templating helper will be a string that will be compared to the rule value.

For body and query string, if the property is an array, Mockoon will automatically check in the array if at least one item matches the value.

 3. Invert operator

You can invert the comparison operator (! equals, ! regex match, etc.) by toggling on the exclamation mark button:

 4. Comparison operator

Multiple comparison operators are available in each rule:

• equals: asserts that the targeted property is equal to the value.
• regex match: asserts that the targeted property matches the regex value.
• null: asserts that the targeted property is null or absent (for headers or cookies).
• empty array: asserts that the targeted property is an empty array.
• array includes: asserts that the given value is present in the targeted property (array).
• valid JSON schema: asserts that the targeted property is a valid JSON schema. The value must point to a data bucket containing a valid JSON schema (see below).

 5. Value

The value field is the expected value to compare against the targeted property, it can be a simple text value, a regex, or a JSON schema.

It also support templating helpers to create dynamic rules. See the templating helpers documentation for more information.

 Strings and regexes

Depending on the comparison operator chosen, equals, regex match or array includes, you can either set a simple text value like "expected value" or any kind of regex. To use a regex, you must write it without the leading and trailing slashes.

Regex examples: primary|secondary, ^user1-9, UTF-.*.
You can also test for empty values with the following regex: ^$|\s+.

The request number supports simple entries like 1 or 2 but also regexes, allowing you to return a different response for the first 3 calls ^[1-3]$ or failing on odd request indexes [13579]$.

 JSON schemas

The only exception is the valid JSON schema comparison operator. In this case, the value must point to a data bucket containing a valid JSON schema. The schema will be used to validate the targeted property using ajv. In this case, the value field supports the object-path syntax to access the schema stored in a data bucket. Examples: bucketNameOrId, bucketNameOrId.propertyName, etc. The data bucket documentation provides more information on how to create and use JSON schemas.