Menu
Amazon API Gateway
Developer Guide

Set up Basic Request Validation in API Gateway

You can set up request validators in an API's Swagger definition file and then import the Swagger definitions into API Gateway. You can also set them up in the API Gateway console or by calling the API Gateway REST API, AWS CLI, or one of the AWS SDKs. Here, we show how to do this with a Swagger file, in the console, and using the API Gateway REST API.

Set up Basic Request Validation by Importing API Swagger Definition

The following steps describe how to enable basic request validation by importing a Swagger file.

To enable request validation by importing a Swagger file into API Gateway

  1. Declare request validators in Swagger by specifying a set of the x-amazon-apigateway-request-validators.requestValidator objects in the x-amazon-apigateway-request-validators map at the API level. For example, the sample API Swagger file contains the x-amazon-apigateway-request-validators map, with the validators' names as the keys.

    Copy
    { "swagger": "2.0", "info": { "title": “ReqValidation Sample", "version": "1.0.0" }, "schemes": [ "https" ], "basePath": "/v1", "produces": [ "application/json" ], "x-amazon-apigateway-request-validators" : { "all" : { "validateRequestBody" : true, "validateRequestParameters" : true }, "params-only" : { "validateRequestBody" : false, "validateRequestParameters" : true } }, ... }

    You select a validator's name when enabling the validator on the API or on a method, as shown in the next step.

  2. To enable a request validator on all methods of an API, specify an x-amazon-apigateway-request-validator property at the API level of the API Swagger definition file. To enable a request validator on an individual method, specify the x-amazon-apigateway-request-validator property at the method level. For example, the following x-amazon-apigateway-request-validator property enables the params-only validator on all API methods, unless otherwise overridden.

    Copy
    { "swagger": "2.0", "info": { "title": “ReqValidation Sample", "version": "1.0.0" }, "schemes": [ "https" ], "basePath": "/v1", "produces": [ "application/json" ], ... "x-amazon-apigateway-request-validator" : "params-only", ... }

    To enable a request validator on an individual method, specify the x-amazon-apigateway-request-validator property at the method level. For example, the following x-amazon-apigateway-request-validator property enables the all validator on the POST /validation method. This overrides the params-only validator that is inherited from the API.

    Copy
    { "swagger": "2.0", "info": { "title": “ReqValidation Sample", "version": "1.0.0" }, "schemes": [ "https" ], "basePath": "/v1", "produces": [ "application/json" ], ... "paths": { "/validation": { "post": { "x-amazon-apigateway-request-validator" : "all", ... }, ... } } ... }

  3. In API Gateway, create the API with request validators enabled by importing this Sample API Swagger Definition:

    Copy
    POST /restapis?mode=import&failonwarning=true HTTP/1.1 Content-Type: application/json Host: apigateway.us-east-1.amazonaws.com X-Amz-Date: 20170306T234936Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170306/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash} Copy the JSON object from this API Swagger Definition and paste it here.
  4. Deploy the newly created API (fjd6crafxc) to a specified stage (testStage).

    Copy
    POST /restapis/fjd6crafxc/deployments HTTP/1.1 Content-Type: application/json Host: apigateway.us-east-1.amazonaws.com X-Amz-Date: 20170306T234936Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170306/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash} { "stageName" : "testStage", "stageDescription" : "Test stage", "description" : "First deployment", "cacheClusterEnabled" : "false" }

For instructions on how to test the request validation using the API Gateway REST API, see Test Basic Request Validation Using the API Gateway REST API. For instructions on how to test using the API Gateway console, see Test Basic Request Validation Using the API Gateway Console.

Set up Request Validators Using the API Gateway REST API

In the API Gateway REST API, a request validator is represented by a RequestValidator resource. To have an API support the same request validators as the Sample API, add to the RequestValidators collection a parameters-only validator with params-only as the key, and add a full validator with all as its key.

To enable the basic request validation using the API Gateway REST API

We assume that you have an API similar to the sample API, but have not set up the request validators. If your API already has request validators enabled, call the appropriate requestvalidator:update or method:put action instead of requestvalidator:create or method:put.

  1. To set up the params-only request validator, call the requestvalidator:create action as follows:

    Copy
    POST /restapis/restapi-id/requestvalidators HTTP/1.1 Content-Type: application/json Host: apigateway.region.amazonaws.com X-Amz-Date: 20170223T172652Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170223/region/apigateway/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature={sig4_hash} { "name" : "params-only", "validateRequestBody" : "false", "validateRequestParameters" : "true" }
  2. To set up the all request validator, call the requestvalidator:create action as follows:

    Copy
    POST /restapis/restapi-id/requestvalidators HTTP/1.1 Content-Type: application/json Host: apigateway.region.amazonaws.com X-Amz-Date: 20170223T172652Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170223/region/apigateway/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature={sig4_hash} { "name" : "all", "validateRequestBody" : "true", "validateRequestParameters" : "true" }

    If the preceding validator keys already exist in the RequestValidators map, call the requestvalidator:update action instead to reset the validation rules.

  3. To apply the all request validator to the POST method, call method:put to enable the specified validator (as identified by the requestValidatorId property) or call method:update to update the enabled validator.

    Copy
    PUT /restapis/restapi-id/resources/resource-id/methods/POST HTTP/1.1 Content-Type: application/json Host: apigateway.region.amazonaws.com X-Amz-Date: 20170223T172652Z Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20170223/region/apigateway/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature={sig4_hash} { "authorizationType" : "NONE", ..., "requestValidatorId" : "all" }

Set up Basic Request Validation Using the API Gateway Console

The API Gateway console lets you set up the basic request validation on a method using one of the three validators:

  • Validate body: This is the body-only validator.

  • Validate query string parameters and headers: This is the parameters-only validator.

  • Validate body, query string parameters, and headers: This validator is for both body and parameters validation.

When you choose one of the above validators to enable it on an API method, the API Gateway console will add the validator to the API's RequestValidators map, if the validator has not already been added to the validators map of the API.

To enable a request validator on a method

  1. Sign in to the API Gateway console, if not already logged in.

  2. Create a new or choose an existing API.

  3. Create a new or choose an existing resource of the API.

  4. Create a new or choose an existing method the resource.

  5. Choose Method Request.

  6. Choose the pencil icon of Request Validator under Settings.

  7. Choose Validate body, Validate query string parameters and headers or Validate body, query string parameters, and headers from the Request Validator drop-down list and then choose the check mark icon to save your choice.

To test and use the request validator in the console, follow the instructions in Test Basic Request Validation Using the API Gateway Console.