`message-template`

Use the message-template policy to create a mock API response.

Before you begin

Table 1. Gateway support for the Message template policy
Gateway	Policy version
DataPower® API Gateway	2.0.0

This topic describes how to configure the policy in your OpenAPI source. For details about how to configure the policy in the assembly user interface, see Message template.

About

The message-template policy has the following format:

- message-template:
  version: 2.0.0
  title: title
  description: description
  template:
    {
           .
    }
  response-object-variable: variable_name
  content-type: application/json

Apply this policy by adding an assembly extension with an execute field to your OpenAPI definition file.

Properties

Table 2. `message-template` policy properties
Property	Required	Description	Data type
version	Yes	The policy version number. You must specify a version for the policy that is compatible with the gateway that you are using. When the API is published, if the version is incompatible with the gateway, a validation error is thrown that specifies the available versions.	string
title	Yes	The title of the policy.	string
description	No	A description of the policy.	string
template	Yes	The example message for the response. The message template can be any form of structured data, such as JSON or XML, or plain text. See the Examples section for some examples of message templates.	string
response-object-variable	No	The name of a variable that is used to store the response data from the request. By default, `message` is used. Use this property to specify an alternate location to store the message response. This variable can then be referenced in other actions, such as Map. Note: If you want the response to be saved in `message`, leave the variable property blank, do not supply the value `message`.	string
content-type	Yes	Determines the `content-type` value that is applied to the message body. Defaults to the `produces` type of the API, but doesn't have to be this value. An API can produce different response content types for different operations or status codes. You can select from the following options: `application/json` `text/plain`	string

Examples

Example 1: Static mock API response

A Handlebars template with no expressions, which means that the output from executing the template is just the template contents. In this example, the output is a JSON document.

{
  "orderNumber": "OU812",
  "orderItems": [
    {
      "itemCode": "7013-520",
      "quantity": 1
    },
    {
      "itemCode": "7013-590",
      "quantity": 1
    }
  ]
}

Example 2: API response with dynamic content

This example expands on Example 1, with the addition of a value taken from the request.

{
  "customerId":
    "{{?request.parameters.customerId}}",
  "orderNumber": "OU812",
  "orderItems": [
    {
      "itemCode": "7013-520",
      "quantity": 1
    },
    {
      "itemCode": "7013-590",
      "quantity": 1
    }
  ]
}

Here, the customerId value is obtained by using a simple Handlebars expression that reads a property value from the input context. The result is that the customerId property value that's returned in the response, is the value from the parameter in the API request. Expressions like this example can be used to insert the data of any form, not just JSON property values.

Example 3: Conditional logic within the template

This example uses the built-in capability of the Handlebars template language to use conditional expressions.

{
  {{#if request.headers.app-context}}
    "context": "{{?request.headers.app-context}}",
  {{/if}}
    "customerId":
      "{{?request.parameters.customerId}}",
    "orderNumber": "OU812",
    "orderItems": [
      {
        "itemCode": "7013-520",
        "quantity": 1
      },
      {
        "itemCode": "7013-590",
        "quantity": 1
      }
    ]
}

Here, a context property is included in the generated response by using the value of the app-context header, if this value is present in the request. Handlebars also includes built-in support for loops, if-then-else, and so on.

Note: Mock APIs aren't restricted to producing a single response, or prevented from mixing mock responses with real backend invocations. For example, you can create assembly logic that returns a response from an Invoke policy, as well as multiple mock responses.