Request validation for WebSocket APIs in API Gateway
You can configure API Gateway to perform validation on a route request before proceeding with the integration request. If the validation fails, API Gateway fails the request without calling your backend, sends a "Bad request body" gateway response to the client, and publishes the validation results in CloudWatch Logs. Using validation this way reduces unnecessary calls to your API backend.
Model selection expressions
You can use a model selection expression to dynamically validate requests within the same
route. Model validation occurs if you provide a model selection expression for either
proxy or non-proxy integrations. You might need to define the $default
model as a fallback when no matching model is found. If there is no matching model and
$default
isn't defined, the validation fails. The selection expression
looks like Route.ModelSelectionExpression
and evaluates to the key for
Route.RequestModels
.
When you define a route for a WebSocket API, you can optionally specify a model
selection expression. This expression is evaluated to select the model to
be used for body validation when a request is received. The expression evaluates to one
of the entries in a route's requestmodels
.
A model is expressed as a JSON schema
Set up request validation using the API Gateway console
The following example shows you how to set up request validation on a route.
First, you create a model, and then you create a route. Next, you configure request validation on the route you just created. Lastly, you deploy and
test your API. To complete this tutorial, you need a WebSocket API with
$request.body.action
as the route selection expression and an integration endpoint for your new route.
You also need wscat
to connect to your API. For more information, see Use wscat to
connect to a WebSocket API and send messages to it.
To create a model
Sign in to the API Gateway console at https://console.aws.amazon.com/apigateway
. Choose a WebSocket API.
In the main navigation pane, choose Models.
Choose Create model.
For Name, enter
emailModel
.For Content type, enter
application/json
.For Model schema, enter the following model:
{ "$schema": "http://json-schema.org/draft-04/schema#", "type" : "object", "required" : [ "address"], "properties" : { "address": { "type": "string" } } }
This model requires that the request contains an email address.
Choose Save.
In this step, you create a route for your WebSocket API.
To create a route
In the main navigation pane, choose Routes.
Choose Create route.
For Route key, enter
sendMessage
.Choose an integration type and specify an integration endpoint. For more information see Integrations for WebSocket APIs in API Gateway.
Choose Create route.
In this step, you set up request validation for the sendMessage
route.
To set up request validation
On the Route request tab, under Route request settings, choose Edit.
For Model selection expression, enter
${request.body.messageType}
.API Gateway uses the
messageType
property to validate the incoming request.Choose Add request model.
For Model key, enter
email
.For Model, choose emailModel.
API Gateway validates incoming messages with the
messageType
property set toemail
against this model.Note
If API Gateway can't match the model selection expression to a model key, then it selects the
$default
model. If there is no$default
model, then the validation fails. For production APIs, we recommend that you create a$default
model.Choose Save changes.
In this step, you deploy and test your API.
To deploy and test your API
Choose Deploy API.
Choose the desired stage from the dropdown list or enter the name of a new stage.
Choose Deploy.
In the main navigation pane, choose Stages.
Copy your API's WebSocket URL. The URL should look like
wss://
.abcdef123
.execute-api.us-east-2
.amazonaws.com/productionOpen a new terminal and run the wscat command with the following parameters.
wscat -c wss://
abcdef123
.execute-api.us-west-2
.amazonaws.com/productionConnected (press CTRL+C to quit)
Use the following command to test your API.
{"action": "sendMessage", "messageType": "email"}
{"message": "Invalid request body", "connectionId":"ABCD1=234", "requestId":"EFGH="}
API Gateway will fail the request.
Use the next command to send a valid request to your API.
{"action": "sendMessage", "messageType": "email", "address": "mary_major@example.com"}