Use Request Data To Create Dynamic Mock Response

Beeceptor takes advantage of the powerful Handlebars templating engine to provide dynamic mocked responses. This allows mocking rules to leverage attributes from the request payload and query parameters to generate responses that are tailored to the specific needs of the request, hence giving a personalized response to each request.

Enabling template in a mocking rule

Beeceptor parses incoming request for request payload and query parameters as a JSON object. This object is available to template engine to be substituted response. Here are a few facts you should know before you start using this.

• The template engine uses Handlebars's syntax.
• By default, template engine is off. You need to explicitly mark a rule to enable usage of Handlebars template.

A handlebars expression is enclosed between {{ and }}. When the template is executed, these expressions are replaced with values from a request object. Beeceptor uses special Handlebars helpers to extract request parameters.

When there are syntax errors in defining templates, Beeceptor tries to recover safely and attempts to generate the mocked response. If there are unrecoverable errors, a response with 561 status code is returned. In such cases, you should review the template syntax and correct it.

Request payload helpers

These helpers allow you to pick any request parameter and send in mocked response.

Syntax

Beeceptor supports following types of template helpers to extract request parameters and add to mocked response. The request payload is parsed only if the entering Content-Type is set to one of below.

• JSON payload - application/json, application/json; charset=utf-8, application/vnd.api+json, application/ld+json, etc.
• Form URL encoded - application/x-www-form-urlencoded

Helper Name	Description & syntax
body	Extracts request payload/body from either JSON or Form URL Encoded. Both of these are built into JSON object to be used in the template. This typically works for POST, PATCH and PUT types of HTTP verbs. Syntax: {{body 'path' 'default-value'}}
queryParam	Extracts query parameters and builds a JSON object to be used in the template. This works for all HTTP verbs. Syntax: {{queryParam 'path' 'default-value'}} The path parameter allows accessing deep properties as flat key-names. Some examples are keyName, parent.child, keyName.1.childKey. This works for JSON Objects and JSON Arrays as object roots.
pathParam	If you are matching a request using regular expression (RegEx) on the request path, you can use named groups. All the named groups and their values are available to be used in the template. Syntax: {{pathParam 'group-name' 'default-value'}} Here is an example where entity_id and child_id are defined as named groups in the mocking rule. These can be accessed in the template body as below:
header	All the request headers are available and can be used in the template. The headers are case-insensitive and you should use lowercase values in this syntax. Syntax: {{header 'header-name' 'default-value'}} Here is an example on how to use header syntax:
Parameter details:

• The path, group-name or header-name are the required parameter in the above syntax.
• The default value parameter is optional, and it falls back to empty string. If no value is found corresponding to given path or first parameter, the default-value is returned.

Examples

Extracting request parameters

Consider a following example with a JSON request payload:

Request: Request payload entering with application/json content-type at server path /my-rule?type=individual

{
	"address": "80, Pearl Residency, MG Road, India",
	"age": 20,
	"name": {"first": "Arti", "last": "Jain"}
}

Mocking Template: Here is an example mocking template defined in a rule.

{
     "type": "{{queryParam 'type'}}",
     "address": "{{body 'address'}}",
     "age": {{body 'age' '0'}},
     "full_name": "{{body 'name.first'}} - {{body 'name.last'}}"
}

Note: In case the request body not carry age attribute, a default value as 0 will be used.

Response: Beeceptor will generate following response body. Here individual is picked from query parameter and rest from the JSON request payload.

{
  "type": "individual",
  "address": "80, Pearl Residency, MG Road, India",
  "age": 20,
  "full_name": "Arti - Jain"
}

Using arrays

Consider an example where the request payload has array of line items when creating an order:

Request: Request payload entering with application/json content-type at server path /orders

{
  "line_items": [
    {
      "id": 110,
      "name": "30g (>1oz) Tiger Tail Pack (Cordyceps Militaris)",
      "product_id": 433,
      "quantity": 1,
      "subtotal": "60.00",
      "total": "60.00",
      "taxes": [],
      "sku": "23423",
      "price": 60,
    }
  ]
}

Mocking Template: To access the line items, you can address array items using indexas defiled in a rule below.

{
    "products": [
      {
        "productId": "{{body 'line_items.0.id'}}",
        "quantity": {{body 'line_items.0.quantity'}},
        "price": {{body 'line_items.0.total'}}
      }
   ]
}

Response: Beeceptor will generate following response body. Here individual is picked from query parameter and rest from the JSON request payload.

{
    "products": [
      {
        "productId": "110",
        "quantity": 1,
        "price": 60
      }
   ]
}