Response templates

Imposter allows you to respond with a template - that is, a file containing placeholders, which are replaced with values at runtime.

Templates can be useful when you are capturing data, using stores or generating data from a script.

Templates can be used with configuration or scripts.

Key concepts

The template engine is enabled by setting template: true in a resource. For example:

# part of your configuration file

resources:
- path: /example
  method: GET
  response:
    template: true
    file: some-template.txt

Templates can be specified as external files, or inline in configuration files.

Here is the same example as above, but using an inline content block:

# part of your configuration file

resources:
- path: /example
  method: GET
  response:
    template: true
    content: |
      Hello ${context.request.pathParams.user}
      This is a templated response.

There are many placeholder types (see placeholder types section), including:

• properties of the request, such as path parameters, query parameters, headers or body
• date/time values, such as timestamps, epoc time in millis, nanos etc.
• data from Stores, including data captured previously
• generating random values, such as UUIDs, numbers, strings etc.
• generating fake data, such as names, addresses, phone numbers etc.

Placeholder types

This section details the placeholder types.

Request path parameters

Syntax: context.request.pathParams.<param name>

Example config:

# part of your configuration file

resources:
- path: /users/{user}
  method: GET
  response:
    content: "Hello ${context.request.pathParams.user}"
    template: true

Example request:

$ curl http://localhost:8080/users/alice

Hello alice

Request query parameters

Syntax: context.request.queryParams.<param name>

Example config:

# part of your configuration file

resources:
- path: /users
  method: GET
  response:
    content: "Hello ${context.request.queryParams.user}"
    template: true

Example request:

$ curl http://localhost:8080/users?user=alice

Hello alice

Request headers

Syntax: context.request.headers.<header name>

Example config:

# part of your configuration file

resources:
- path: /users
  method: GET
  response:
    content: "Hello ${context.request.headers.user}"
    template: true

Example request:

$ curl http://localhost:8080/users -H "user: alice"

Hello alice

Request body

Syntax: context.request.body

Example config:

# part of your configuration file

resources:
- path: /users
  method: POST
  response:
    content: "Hello ${context.request.body}"
    template: true

Example request:

$ curl http://localhost:8080/users --data "alice"

Hello alice

Note: the use of curl's --data argument implies this is a POST request, with the value alice sent as the request body.

Request form parameters

Syntax: context.request.formParams.<param name>

Example config:

# part of your configuration file

resources:
- path: /users
  method: POST
  response:
    content: "Hello ${context.request.formParams.user}"
    template: true

Example request:

$ curl http://localhost:8080/users --data-urlencode "user=alice"

Hello alice

Date/time values

Syntax: datetime.now.<property>

Example config:

# part of your configuration file

resources:
- path: /now
  method: POST
  response:
    content: "The date is ${datetime.now.iso8601_date}"
    template: true

Example request:

$ curl http://localhost:8080/now

The date is 2022-12-28

Valid date/time properties:

Syntax	Example	Example value
datetime.now.iso8601_date	${datetime.now.iso8601_date}	"2022-01-20"
datetime.now.iso8601_datetime	${datetime.now.iso8601_datetime}	"2022-01-20T14:23:25.737Z"
datetime.now.millis	${datetime.now.millis}	"1642688570140"
datetime.now.nanos	${datetime.now.nanos}	"30225267785430"

Random values

Syntax: random.<function>

Example config:

# part of your configuration file

resources:
- path: /now
  method: POST
  response:
    content: "An integer is ${random.numeric}"
    template: true

Example request:

$ curl http://localhost:8080/now

An integer is 42

Valid random functions:

Syntax	Example	Example value
random.alphabetic()	${random.alphabetic()}	"i"
random.alphanumeric()	${random.alphanumeric()}	"i" or "42"
random.numeric()	${random.numeric()}	"42"
random.uuid()	${random.uuid()}	"e1a4fba9-33eb-4241-84cf-472f90639c37"

Note: the syntax for random is slightly different to the other placeholder types. These are functions, not properties, so are called with parentheses.

Items in a Store

You can use items from a Store, including data captured previously, or set by a script.

Syntax: stores.<store name>.<item name>

For example, a template file might look like this:

{
  "userName": "${stores.testStore.person}"
}

The placeholder ${stores.testStore.person} refers to an item named 'person' in the store named 'testStore'.

Learn more about stores.

---

Script-driven templates

When you are using scripting to control mock behaviour, you can use the template() method, as follows:

respond().withFile('example-template.json').template();

As with the configuration-driven approach described above, your template includes placeholders.

A common pattern is to use a script to retrieve items from a store, or generate values dynamically and set them in a store, for use in a template.

---

Using JsonPath in placeholders

You can use a JsonPath expression to query an object when using a placeholder.

See the template queries page for more details.

Templating performance

Templating incurs a performance penalty, but is often faster than dynamically generating large objects using scripts, so is generally a better tradeoff when dynamic responses are required.

Template files are cached in memory once read from disk, so they do not incur as high an I/O cost from storage on subsequent requests.

Examples

• response-template