Setting up a WebSocket API integration responses in API Gateway
Topics
Overview of integration responses
API Gateway's integration response is a way of modeling and manipulating the response from a backend service. There are some differences in setup of a REST API versus a WebSocket API integration response, but conceptually the behavior is the same.
WebSocket routes can be configured for two-way or one-way communication.
-
When a route is configured for two-way communication, an integration response allows you to configure transformations on the returned message payload, similar to integration responses for REST APIs.
-
If a route is configured for one-way communication, then regardless of any integration response configuration, no response will be returned over the WebSocket channel after the message is processed.
API Gateway will not pass the backend response through to the route response, unless you set up a route response. To learn about setting up a route response, see Set up route responses for a WebSocket API in API Gateway.
Integration responses for two-way communication
Integrations can be divided into proxy integrations and non-proxy integrations.
Important
For proxy integrations, API Gateway automatically passes the backend output to the caller as the complete payload. There is no integration response.
For non-proxy integrations, you must set up at least one integration response:
-
Ideally, one of your integration responses should act as a catch-all when no explicit choice can be made. This default case is represented by setting an integration response key of
$default. -
In all other cases, the integration response key functions as a regular expression. It should follow a format of
"/expression/".
For non-proxy HTTP integrations:
-
API Gateway will attempt to match the HTTP status code of the backend response. The integration response key will function as a regular expression in this case. If a match cannot be found, then
$defaultis chosen as the integration response. -
The template selection expression, as described above, functions identically. For example:
-
/2\d\d/: Receive and transform successful responses -
/4\d\d/: Receive and transform bad request errors -
$default: Receive and transform all unexpected responses
-
For more information about template selection expressions, see Template selection expressions.
Set up an integration response using the API Gateway console
To set up a route integration response for a WebSocket API using the API Gateway console:
-
Sign in to the API Gateway console at https://console.amazonaws.cn/apigateway
. -
Choose your WebSocket API and choose your route.
-
Choose the Integration request tab, and then in the Integration response settings section, choose Create integration response.
-
For Response key, enter a value that will be found in the response key in the outgoing message after evaluating the response selection expression. For instance, you can enter
/4\d\d/to receive and transform bad request errors or enter$defaultto receive and transform all responses that match the template selection expression. -
For Template selection expression, enter a selection expression to evaluate the outgoing message.
-
Choose Create response.
You can also define a mapping template to configure transformations of your returned message payload. Choose Create template.
Enter a key name. If you are choosing the default template selection expression, enter
\$default.-
For Response template, enter your mapping template in the code editor.
-
Choose Create template.
-
Choose Deploy API to deploy your API.
Use the following wscatwscat, see Use wscat to
connect to a WebSocket API and send messages to it.
wscat -c wss://api-id.execute-api.us-west-2.amazonaws.com/test
When you call your route, the returned message payload should return.
Set up an integration response using the Amazon CLI
To set up an integration response for a WebSocket API using the Amazon CLI call the
create-integration-response command. The following CLI
command shows an example of creating a $default integration response:
aws apigatewayv2 create-integration-response \ --api-id vaz7da96z6 \ --integration-id a1b2c3 \ --integration-response-key '$default'