Message template

How to configure a Message template policy to create a mock API response for the DataPower® API Gateway in the assembly editor.

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 the assembly editor. For details about how to configure the policy in your OpenAPI source, see message-template.

About this task

You can configure a Message template policy to create a mock API response for the DataPower API Gateway. Usually, an API response is obtained by creating an Invoke policy in your API that interacts with a backend service. However, you can use the Message template policy to produce a mock response internally by using the assembly logic, without needing to interact with a separate backend service. This mock response can return a simple literal response, such as a JSON document, or it can include dynamic content such as values that are derived from the request, or from other parts of the assembly context.

You can complete this task either by using the API Designer UI application, or by using the browser-based API Manager UI.

Procedure

In the navigation pane, click Develop, then select the APIs tab.
The Develop page opens.
Click the title of the API definition that you want to work with.
Select the Gateway tab, then click Policies in the navigation pane.
For more information about working with the assembly editor for an API, see The assembly editor.
Find the Message template policy in the palette, and drag the policy onto your canvas.

Specify the following properties.

Table 2. Message template policy properties
Property label	Required	Description	Data type
Title	Yes	The title of the policy. The default value is `message-template`.	string
Description	No	A description of the policy.	string
Template	Yes	The text content of the template that is executed at runtime The content 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 will be 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 Response object 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

Specify a version for the policy by clicking the Source icon , and completing the version section of the policy YAML. For example:
```
execute:
  - message-template:
      version: 2.0.0
      title: message
...
```
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.
Click Save.

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.

What to do next

You can now use the Test tab to test your mock API response.