Create routes for WebSocket APIs in API Gateway

In your WebSocket API, incoming JSON messages are directed to backend integrations based on routes that you configure. (Non-JSON messages are directed to a $default route that you configure.)

A route includes a route key, which is the value that is expected once a route selection expression is evaluated. The routeSelectionExpression is an attribute defined at the API level. It specifies a JSON property that is expected to be present in the message payload. For more information about route selection expressions, see Route selection expressions.

For example, if your JSON messages contain an action property and you want to perform different actions based on this property, your route selection expression might be ${request.body.action}. Your routing table would specify which action to perform by matching the value of the action property against the custom route key values that you have defined in the table.

There are three predefined routes that can be used: $connect, $disconnect, and $default. In addition, you can create custom routes.

Route selection expressions

A route selection expression is evaluated when the service is selecting the route to follow for an incoming message. The service uses the route whose routeKey exactly matches the evaluated value. If none match and a route with the $default route key exists, that route is selected. If no routes match the evaluated value and there is no $default route, the service returns an error. For WebSocket-based APIs, the expression should be of the form $request.body.{path_to_body_element}.

For example, suppose you are sending the following JSON message:

{
    "service" : "chat",
    "action" : "join",
    "data" : {
        "room" : "room1234"
   }
}

You might want to select your API's behavior based on the action property. In that case, you might define the following route selection expression:

$request.body.action

In this example, request.body refers to your message's JSON payload, and .action is a JSONPath expression. You can use any JSON path expression after request.body, but keep in mind that the result will be stringified. For example, if your JSONPath expression returns an array of two elements, that will be presented as the string "[item1, item2]". For this reason, it's a good practice to have your expression evaluate to a value and not an array or an object.

You can simply use a static value, or you can use multiple variables. The following table shows examples and their evaluated results against the preceding payload.

The evaluated result is used to find a route. If there is a route with a matching route key, the route is selected to process the message. If no matching route is found, then API Gateway tries to find the $default route if available. If the $default route is not defined, then API Gateway returns an error.

Set up routes for a WebSocket API in API Gateway

When you first create a new WebSocket API, there are three predefined routes: $connect, $disconnect, and $default. You can create them by using the console, API, or AWS CLI. If desired, you can create custom routes. For more information, see Overview of WebSocket APIs in API Gateway.

Create a route using the API Gateway console

Create a route using the AWS CLI

The following create-route command creates a route:

aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default

The output will look like a following:

{
    "ApiKeyRequired": false,
    "AuthorizationType": "NONE",
    "RouteKey": "$default",
    "RouteId": "1122334"
}

Specify route request settings for $connect

When you set up the $connect route for your API, the following optional settings are available to enable authorization for your API. For more information, see The $connect route.

Set up the $connect route request using the API Gateway console

To set up the $connect route request for a WebSocket API using the API Gateway console: