Templating request helpers

Mockoon offers the following helpers which can return information relative to the entering request:

• body
• bodyRaw
• queryParam
• queryParamRaw
• queryParams
• urlParam
• urlParams
• cookie
• header
• headers
• hostname
• ip
• method
• baseUrl

 body

Get the value at a given path from the request's body if the Content-Type is set to application/json, application/x-www-form-urlencoded, multipart/form-data, application/xml, application/soap+xml or text/xml. This helper is designed to retrieve data, stringify it, it order to use it directly in a response. To reuse the retrieved data (strings, booleans, arrays, etc.) with other helpers (each, if, etc.), use the bodyRaw helper below.

• The path supports two syntaxes, object-path or JSONPath Plus. When using object-path, properties containing dots are supported by escaping the dots: key.key\.with\.dot.

• XML bodies are parsed using xml-js package. Please refer to this page or the package documentation for more information on how the XML is parsed and how to fetch specific properties.

• multipart/form-data supports fields and files. Uploaded files will not be stored, but their metadata (filename, mimetype, size) will be available in the request body:

  Copy
  {
    "field1": "value1",
    "file1": {
      "filename": "file1.txt",
      "mimetype": "text/plain",
      "size": 1234
    }
  }

• Full objects or arrays can be retrieved by the helper.

• The full request's body can also be fetched when the path is omitted ({{body}}) independently from the request's Content-Type.

• If no value is present at the requested path, the default value will be used.

• A third parameter (boolean) can be set to true to returns a stringified value even if it's a primitive.

Examples

Copy
{{body}}

<!-- Using object-path syntax -->
{{body 'path.to.property'}}
{{body 'deep.property\.with\.dot'}}

<!-- using JSONPath syntax -->
{{body '$.array.[*].property'}}

{{body 'path' 'default value'}}
{{body 'path' 'default value' true}}

 bodyRaw

Get the raw value (string, boolean, array, etc.) at a given path from the request's body if the Content-Type is set to application/json, application/x-www-form-urlencoded, multipart/form-data, application/xml, application/soap+xml or text/xml. This "raw" helper is designed to give you access to the values to use them with other helpers (each, if, etc.). To directly use the stringified data in the response, use the body helper above.

• The path supports two syntaxes, object-path or JSONPath Plus. When using object-path, properties containing dots are supported by escaping the dots: key.key\.with\.dot.

• XML bodies are parsed using xml-js package. PLease refer to this page or the package documentation for more information on how the XML is parsed and how to fetch specific properties.

• multipart/form-data only supports fields and files. Uploaded files will not be stored, but their metadata (filename, mimetype, size) will be available in the request body:

  Copy
  {
    "field1": "value1",
    "file1": {
      "filename": "file1.txt",
      "mimetype": "text/plain",
      "size": 1234
    }
  }

• Full objects or arrays can be retrieved by the helper.

• The full request's raw body can also be fetched when the path is omitted ({{bodyRaw}}) independently from the request's Content-Type.

• If no value is present at the requested path, the default value will be used.

• This helper allows the use of body within handlebars' helpers such as {{#each}} and {{#if}}.

Examples

Copy
{{bodyRaw}}

<!-- Using object-path syntax -->
{{bodyRaw 'path.to.property'}}
{{bodyRaw 'deep.property\.with\.dot'}}

<!-- using JSONPath syntax -->
{{bodyRaw '$.array.[*].property'}}

{{bodyRaw 'path' 'default value'}}

{{#each (bodyRaw 'path.to.array.property' 'default value')}}
  value
{{/each}}

{{#if (bodyRaw 'path.to.boolean.property' 'default value')}}
  value
{{/if}}

 queryParam

Get the value at a given path from the request's query string. Complex query strings with arrays and objects are supported. This helper is designed to retrieve data to be served in a response. To reuse the retrieved data with other helpers (each, if, etc.), use the queryParamRaw helper below.

• The path supports two syntaxes, object-path or JSONPath Plus. When using object-path, properties containing dots are supported by escaping the dots: key.key\.with\.dot.
• Full objects or arrays can be retrieved by the helper.
• The full query string object can also be fetched when the path is omitted ({{queryParam}}). It will be stringified and can be used in a JSON body for example.
• If there is no value at the requested path, the default value will be used.
• A third parameter (boolean) can be set to true to returns a stringified value even if it's a primitive.

Examples

Copy
{{queryParam}}

<!-- Using object-path syntax -->
{{queryParam 'path.to.property'}}
{{queryParam 'deep.property\.with\.dot'}}

<!-- using JSONPath syntax -->
{{queryParam '$.array.[*].property'}}

{{queryParam 'path' 'default value'}}
{{queryParam 'path' 'default value' true}}

 queryParamRaw

Get the raw value at a given path from the request's query string. Complex query strings with arrays and objects are supported. This "raw" helper is designed to work with other helpers (each, if, etc.). To directly use the retrieved data in the response, use the queryParam helper above.

• The path supports two syntaxes, object-path or JSONPath Plus. When using object-path, properties containing dots are supported by escaping the dots: key.key\.with\.dot.
• Full objects or arrays can be retrieved by the helper.
• The full query string object can also be fetched when the path is omitted ({{queryParamRaw}}).
• If there is no value at the requested path, the default value will be used.
• This helper allows the use of queryParam within handlebars' helpers such as {{#each}} and {{#if}}.

Examples

Copy
{{queryParamRaw}}

<!-- Using object-path syntax -->
{{queryParamRaw 'path.to.property'}}
{{queryParamRaw 'deep.property\.with\.dot'}}

<!-- using JSONPath syntax -->
{{queryParamRaw '$.array.[*].property'}}

{{queryParamRaw 'path' 'default value'}}

{{#each (queryParamRaw 'path.to.array.query' 'default value')}}
  value
{{/each}}

{{#if (queryParamRaw 'path.to.boolean.query' 'default value')}}
  value
{{/if}}

 queryParams

Returns an object containing all query parameters from the request URL. This helper is useful for iterating over all query parameters.

Examples

Copy
<!-- Iterate over all query parameters -->
{{#each (queryParams)}}
  {{@key}}:{{this}}
{{/each}}

<!-- Get all query parameters as JSON -->
{{{stringify (queryParams)}}}

<!-- Check if a specific query parameter exists -->
{{#if (lookup (queryParams) 'page')}}
  Page parameter provided:
  {{lookup (queryParams) 'page'}}
{{/if}}

 urlParam

Get a named parameter from the route /:paramName1/:paramName2.

Examples

Copy
{{urlParam 'paramName1'}}

 urlParams

Returns an object containing all URL parameters from the route. This helper is useful for iterating over all URL parameters.

Examples

Copy
<!-- Iterate over all URL parameters -->
{{#each (urlParams)}}
  {{@key}}:{{this}}
{{/each}}

<!-- Get all URL parameters as JSON -->
{{{stringify (urlParams)}}}

<!-- Check if a specific URL parameter exists -->
{{#if (lookup (urlParams) 'userId')}}
  User ID provided:
  {{lookup (urlParams) 'userId'}}
{{/if}}

 cookie

Get the content of a cookie or returns a default value if the cookie is not present.

Examples

Copy
{{cookie 'cookie_name' 'default value'}}

 header

Get content from any request header or returns a default value if header is not present.

Examples

Copy
{{header 'Header-Name' 'default value'}}

 headers

Returns an object containing all request headers. This helper is useful for iterating over all headers.

Examples

Copy
<!-- Iterate over all headers -->
{{#each (headers)}}
  {{@key}}:{{this}}
{{/each}}

<!-- Get all headers as JSON -->
{{{stringify (headers)}}}

<!-- Check if a specific header exists -->
{{#if (lookup (headers) 'authorization')}}
  Authorization header provided
{{/if}}

 hostname

Returns the request hostname.

Examples

Copy
{{hostname}}

 ip

Returns the request IP address.

Examples

Copy
{{ip}}

 method

Returns the request method (GET, PUT, POST, etc.).

Examples

Copy
{{method}}

 baseUrl

Returns the base URL of the request: protocol, host, port and API prefix.

Examples

Copy
{{baseUrl}}