Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Setting up data transformations for WebSocket APIs

In API Gateway, a WebSocket API's method request can take a payload in a different format from the corresponding integration request payload, as required in the backend. Similarly, the backend may return an integration response payload different from the method response payload, as expected by the frontend.

API Gateway lets you use mapping templates to map the payload from a method request to the corresponding integration request and from an integration response to the corresponding method response. You specify a template selection expression to determine which template to use to perform the necessary data transformations.

You can use data mappings to map data from a route request to a backend integration. To learn more, see Setting up data mapping for WebSocket APIs.

Mapping templates and models

A mapping template is a script expressed in Velocity Template Language (VTL) and applied to the payload using JSONPath expressions. For more information about API Gateway mapping templates, see Understanding mapping templates.

The payload can have a data model according to the JSON schema draft 4. You do not have to define a model to create a mapping template. However, a model can help you create a template because API Gateway generates a template blueprint based on a provided model. For more information about API Gateway models, see Understanding data models.

Template selection expressions

To transform a payload with a mapping template, you specify a WebSocket API template selection expression in an integration request or integration response. This expression is evaluated to determine the input or output template (if any) to use to transform either the request body into the integration request body (via an input template) or the integration response body to the route response body (via an output template).

Integration.TemplateSelectionExpression supports ${request.body.jsonPath} and static values.

IntegrationResponse.TemplateSelectionExpression supports ${request.body.jsonPath}, ${integration.response.statuscode}, ${integration.response.header.headerName}, ${integration.response.multivalueheader.headerName}, and static values.

Integration response selection expressions

When you set up an integration response for a WebSocket API, you can optionally specify an integration response selection expression. This expression determines what IntegrationResponse should be selected when an integration returns. The value of this expression is currently restricted by API Gateway, as defined below. Realize that this expression is only relevant for non-proxy integrations; a proxy integration simply passes the response payload back to the caller without modeling or modification.

Unlike the other preceding selection expressions, this expression currently supports a pattern-matching format. The expression should be wrapped with forward slashes.

Currently the value is fixed depending on the integrationType: