Simula Template Placeholders

One type of fragments in a Simula template that can produce variable content is the placeholders.

By default, ${ and } denote the beginning and end of a placeholder.

The following example is for a simlet that simulates the HTTP response to a request to create new product; product data like Product ID, name, etc. are in the body of the request:

In the example above, ${ProductID} is a placeholder for the actual Product ID. Its value will be resolved upon rendering the template by trying to look it up in the list of placeholders (see below) first and, if not found there, to find it in the list of parameters next.

In this way, a single simlet simulates the creation of different products without having to "know" all possible Product IDs in advance. The simlet extracts the Product ID from the request and puts it into a parameter that a placeholder then uses to produce dynamic output.

The ${ProductID} placeholder doesn’t have any formatting - the template engine will replace ${ProductID} with the "raw" parameter value.

It is possible to apply formatting to a placeholder’s value. Moreover, API Simulator supports encoding of placeholder values so that special characters in them won’t break the output. JSON, XML, HTML, URL, Base64, and Base64Url encoders are currently supported.

API Simulator doesn’t automatically escape all placeholder values. That makes it possible to inject invalid content in a given context (e.g. JSON body) and test how API clients deal with it.

API Simulator will error out if it can’t find the parameter for a placeholder, log an "Unresolvable token=<name-here>" error, and return 500 Internal Server Error response.

Template Functions offer great flexibility in 'shaping' the placeholder values before they are rendered as part of a template.

The following applies to all template functions:

…​will output in the response body this properly encoded JSON string:

When the HTTP response body is in JSON format and one wants to use a template function that expects a string argument but the value of the argument itself contains single quotes, then escape the single quotes inside the argument’s value. For example:

Placeholder values may be of a scalar data type - string, boolean, integer, floating point number, or datetime - or they can have complex data structure. Placeholders in a Simula template can use expressions to access properties and elements of such complex values. For example, to access a list element by its index/position in the list or to access a map element by key (map is a data structure with key/value pairs for elements and where a value - scalar or complex - is identified by its key).

This can be very useful when used on its own or when used in scriptlets.

The following examples demonstrates working with URI Query String Parameters. A URI Query String Parameters parameter is like a map with elements having Query String Parameter names as keys and values are lists of zero or more Query String Parameter values of type string:

Assuming this GET request:

…​here is how the response body built with the template will look like:

The example demonstrated calling methods inside placeholders like count() and get(name, index), accessing an element in a list by index - .get(index) or [index]…​and even an embedded calculation - computing the last index (when we know that there’s at least one element).

See also Request Object Reference for all the methods valid for URI Query String Parameters or an individual URI Query String Parameter.

When a variable or parameter is not defined or is null, this is a way to specify a default value for it:

While it is possible to have ${ …​ } placeholders inside <% …​ %> scriptlets, it is an error to place <% …​ %> scriptlets inside ${ …​ } placeholders.

We would love to hear your feedback! Shoot us an email to [feedback at APISimulator.com] about anything that is on your mind.

Happy API Simulating!