Templating request helpers

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

• body
• bodyRaw
• queryParam
• queryParamRaw
• urlParam
• cookie
• header
• 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}}

 urlParam

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

Examples

Copy
{{urlParam 'paramName1'}}

 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'}}

 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}}