In the post, Understanding Amazon API Gateway: Methods and Integrations, we discussed how the method request section manages authorization, API KEY checks, and request validation. We've already covered authorization in articles like How to Secure AWS Lambda Functions Using Amazon API Gateway and AWS IAM and How to Use Lambda Authorizers to Validate Microsoft EntraID (Azure AD) Tokens in Amazon API Gateway. For API KEY checks, see How to Throttle Requests in Amazon API Gateway. Today, we'll focus on the missing piece: request validation.
Pre-requisites
An IAM User with programmatic access
Install the AWS CLI
Install the Amazon Lambda Templates (dotnet new -i Amazon.Lambda.Templates)
Install the Amazon Lambda Tools (dotnet tool install -g Amazon.Lambda.Tools)
Install AWS SAM CLI
The Lambda function
Run the following commands to set up our Lambda function:
dotnet new lambda.EmptyFunction -n MyLambda -o .
dotnet add src/MyLambda package Amazon.Lambda.APIGatewayEvents
dotnet new sln -n MyApplications
dotnet sln add --in-root src/MyLambda
Open the Program.cs file and update the content as follows:
using Amazon.Lambda.APIGatewayEvents;
using Amazon.Lambda.Core;
using System.Text.Json;
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]
namespace MyLambda;
public class Function
{
public record RegisterPetRequest(string Name);
public record RegisterPetResponse(Guid PetId, string Name);
private readonly JsonSerializerOptions _options;
public Function()
{
_options = new JsonSerializerOptions()
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
};
}
public APIGatewayHttpApiV2ProxyResponse FunctionHandler(APIGatewayHttpApiV2ProxyRequest input, ILambdaContext context)
{
var request = JsonSerializer.Deserialize<RegisterPetRequest>(input.Body, _options)!;
var body = JsonSerializer.Serialize(new RegisterPetResponse(Guid.NewGuid(), request.Name), _options);
return new APIGatewayHttpApiV2ProxyResponse
{
Body = body,
StatusCode = 200,
Headers = new Dictionary<string, string> { { "Content-Type", "application/json" } }
};
}
}
AWS SAM template
At the solution level, create a template.yml file with the following content:
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
SAM
Resources:
MyApi:
Type: AWS::Serverless::Api
Properties:
StageName: prod
MyApiFunction:
Type: AWS::Serverless::Function
Properties:
Timeout: 60
MemorySize: 512
Tracing: Active
Runtime: dotnet8
Architectures:
- x86_64
Handler: MyLambda::MyLambda.Function::FunctionHandler
CodeUri: ./src/MyLambda/
Events:
Post:
Type: Api
Properties:
RestApiId: !Ref MyApi
Path: /pets
Method: post
Outputs:
MyApiEndpoint:
Description: "API endpoint"
Value: !Sub "https://${MyApi}.execute-api.${AWS::Region}.amazonaws.com/prod/pets"
Run the following commands to deploy the resources to AWS:
sam build
sam deploy --guided
Body Validation
We can define a JSON schema as a model that Amazon API Gateway will use to validate that the request body matches this schema. Update the template.yml file as follows:
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
SAM
Resources:
MyApi:
Type: AWS::Serverless::Api
Properties:
StageName: prod
Models:
RegisterPetRequest:
type: "object"
properties:
name:
type: "string"
minLength: 1
required:
- name
MyApiFunction:
Type: AWS::Serverless::Function
Properties:
Timeout: 60
MemorySize: 512
Tracing: Active
Runtime: dotnet8
Architectures:
- x86_64
Handler: MyLambda::MyLambda.Function::FunctionHandler
CodeUri: ./src/MyLambda/
Events:
Post:
Type: Api
Properties:
RestApiId: !Ref MyApi
Path: /pets
Method: post
RequestModel:
Model: RegisterPetRequest
ValidateBody: true
Outputs:
MyApiEndpoint:
Description: "API endpoint"
Value: !Sub "https://${MyApi}.execute-api.${AWS::Region}.amazonaws.com/prod/pets"
The AWS::Serverless::Api resource exposes the Models property, allowing us to define multiple schemas. Then, in the AWS::Serverless::Function under the event source Api, the RequestModel will configure the validation:
Model: The name of the model defined earlier.
ValidateBody: Enable body validation.
ValidateParameters: Enable parameters (path, headers, and query string) validation.
Header And Query String Validation
Amazon API Gateway can validate headers and query string parameters to ensure they are included in the request. Update the AWS::Serverless::Function resource as follows:
MyApiFunction:
Type: AWS::Serverless::Function
Properties:
Timeout: 60
MemorySize: 512
Tracing: Active
Runtime: dotnet8
Architectures:
- x86_64
Handler: MyLambda::MyLambda.Function::FunctionHandler
CodeUri: ./src/MyLambda/
Events:
Post:
Type: Api
Properties:
RestApiId: !Ref MyApi
Path: /pets
Method: post
RequestParameters:
- method.request.header.traceid:
Required: true
- method.request.querystring.version:
Required: true
RequestModel:
Model: RegisterPetRequest
ValidateBody: true
ValidateParameters: true
Within the AWS::Serverless::Function under the event source Api, the RequestParameters will partially set up the validation. We can define multiple request parameters in the following format:
Generally, method.request refers to the incoming request. It allows us to reference different parts of the HTTP request. To complete the configuration, ValidateParameters must be set to true.
If we want to validate only headers and/or query strings, the Model property is still needed, but the ValidateBody property should be set to false.
Gateway Responses
Amazon API Gateway provides a predefined set of responses that automatically handle various errors. When validation fails, Amazon API Gateway returns a 400 status code, and a specific response will be returned depending on the error. In our case, we could expect a BAD_REQUEST_PARAMETERS or BAD_REQUEST_BODY response. These responses, by default, return a short descriptive error message but can be customized based on our needs. Update the AWS::Serverless::Api resource as follows:
MyApi:
Type: AWS::Serverless::Api
Properties:
StageName: prod
GatewayResponses:
BAD_REQUEST_BODY:
ResponseParameters:
Headers:
traceid: "method.request.header.traceid"
ResponseTemplates:
application/json: "{\"type\":\"https://example.net/validation-error\" ,\"detail\": \"$context.error.messageString\", \"title\":\"Validation error\" }"
Models:
RegisterPetRequest:
type: "object"
properties:
name:
type: "string"
minLength: 1
required:
- name
In the AWS::Serverless::Api resource, the GatewayResponses property allows us to define multiple response types with the following structure:
ResponseParameters and ResponseTemplates let us define their content through a template that only supports simple variable substitutions. The template can access $context variable values and $stageVariables property values, as well as method request parameters, in the form of method.request.param-position.param-name.
Conclusions
Performing this kind of validation at the Amazon API Gateway level can eliminate unnecessary calls to the backend, thereby saving money on our bills. Additionally, this information enhances the API definition file, making it easier to understand. Unfortunately, Amazon API Gateway models are defined using the JSON Schema draft #4, which supports only the data types and validations available in this draft. You can find the final code here. Thanks, and happy coding.
