As we discussed in our article Understanding Amazon API Gateway: Methods and Integrations, there are two types of integration with a backend service: proxy and non-proxy.
Proxy Integration
In proxy integration, Amazon API Gateway forwards the entire request to the backend service, which processes the request and returns the response. There are two types of proxy integration: Lambda Proxy Integration and HTTP Proxy Integration. The main advantages are easy configuration and control over the request and response in the backend service. However, this approach limits our ability to manipulate the request and response from the backend service.
Non-Proxy Integration
In non-proxy integration, Amazon API Gateway lets us control how requests are transformed before they are sent to the backend and how responses are returned. We explicitly configure the request and response mappings. There are two types: Lambda Custom Integration and HTTP Custom Integration. The main advantage is having control over the request and response structure, useful when integrating with backends that need specific formats. The downside is the increased complexity during configuration.
In this article, we focus on the last integration type, using a Lambda function as the backend service.
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.Core;
using System.Text.Json;
[assembly: LambdaSerializer(typeof(Amazon.Lambda.Serialization.SystemTextJson.DefaultLambdaJsonSerializer))]
namespace MyLambda;
public class Function
{
public record RegisterPetRequest(string Name, string ThrowError);
public record RegisterPetResponse(Guid PetId, string Name);
public RegisterPetResponse FunctionHandler(RegisterPetRequest input, ILambdaContext context)
{
if (!string.IsNullOrEmpty(input.ThrowError))
{
throw new ApplicationException("An error was thrown");
}
return new RegisterPetResponse(Guid.NewGuid(), input.Name);
}
}
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::ApiGateway::RestApi
Properties:
Description: API with lambda non proxy integration
Name: apilambdanonproxy
EndpointConfiguration:
Types:
- REGIONAL
MyResource:
Type: AWS::ApiGateway::Resource
Properties:
ParentId: !GetAtt MyApi.RootResourceId
PathPart: 'pets'
RestApiId: !Ref MyApi
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/
MyPermission:
Type: AWS::Lambda::Permission
DependsOn:
- MyApi
Properties:
Action: lambda:InvokeFunction
FunctionName: !Ref MyApiFunction
Principal: apigateway.amazonaws.com
Outputs:
MyApiEndpoint:
Description: "API endpoint"
Value: !Sub "https://${MyApi}.execute-api.${AWS::Region}.amazonaws.com/prod/pets"
RestApiId:
Description: "REST API id"
Value: !Ref MyApi
Usually, the AWS::Serverless::Function resource simplifies setting up a Lambda function. However, in our case, it does not support non-proxy integration, so we will use CloudFormation resources to complete the setup.
The AWS::ApiGateway::RestApi resource creates a REST API in Amazon API Gateway.
The AWS::ApiGateway::Resource resource creates a specific URI within our REST API, which can be associated with various HTTP methods.
The AWS::Lambda::Permission resource grants permission for an AWS service or another AWS account to invoke a specific AWS Lambda function.
The AWS::ApiGateway::Method resource represents an HTTP method. This resource defines the settings for a particular HTTP method, such as the integration with the backend service. We will begin with the following setup:
MyMethod:
Type: AWS::ApiGateway::Method
Properties:
ResourceId: !Ref MyResource
RestApiId: !Ref MyApi
Method Request and Method Response
From the method request perspective, we add the AuthorizationType, HttpMethod, and RequestParameters properties. For the method response, we define the 200 and 500 status codes and their corresponding response parameters within the MethodResponses property. Defining the RequestParameters and MethodResponses is necessary to set up and understand the integration section later.
MyMethod:
Type: AWS::ApiGateway::Method
Properties:
ResourceId: !Ref MyResource
RestApiId: !Ref MyApi
AuthorizationType: NONE
HttpMethod: POST
RequestParameters:
method.request.header.version: true
MethodResponses:
- StatusCode: '200'
ResponseParameters:
method.response.header.version: true
method.response.header.id: true
- StatusCode: '500'
ResponseParameters:
method.response.header.version: true
Integration Request
The Integration property contains all the configuration for the backend service:
MyMethod:
Type: AWS::ApiGateway::Method
Properties:
ResourceId: !Ref MyResource
RestApiId: !Ref MyApi
AuthorizationType: NONE
HttpMethod: POST
RequestParameters:
method.request.header.version: true
MethodResponses:
- StatusCode: '200'
ResponseParameters:
method.response.header.version: true
method.response.header.id: true
- StatusCode: '500'
ResponseParameters:
method.response.header.version: true
Integration:
IntegrationHttpMethod: POST
Type: AWS
Uri: !Sub "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${MyApiFunction.Arn}/invocations"
The IntegrationHttpMethod property specifies the HTTP method used to invoke the backend service.
Valid values for the Type property are AWS, AWS_PROXY, HTTP, HTTP_PROXY, and MOCK.
For HTTP and HTTP_PROXY types, the Uri property holds the HTTP URL of our backend service. For AWS or AWS_PROXY types, the value follows the format arn:aws:apigateway:{region}:{subdomain.service|service}:path|action/{service_api}.
Request Mapping
Body
To map the body from the method request to the backend service, we use the RequestTemplates property. The property's value is a dictionary where the content type is the key and the template, written in Velocity Template Language (VTL), is the content. The following list shows the variables we can use during the mapping:
The $input variable lets us access the body, query strings, headers, and path variables.
The $context variable gives information about the Amazon API Gateway execution context.
The $stageVariable can be used to inject environment values from the stage.
The $util variable contains utility functions.
MyMethod:
Type: AWS::ApiGateway::Method
Properties:
ResourceId: !Ref MyResource
RestApiId: !Ref MyApi
AuthorizationType: NONE
HttpMethod: POST
RequestParameters:
method.request.header.version: true
MethodResponses:
- StatusCode: '200'
ResponseParameters:
method.response.header.version: true
method.response.header.id: true
- StatusCode: '500'
ResponseParameters:
method.response.header.version: true
Integration:
PassthroughBehavior: WHEN_NO_TEMPLATES
IntegrationHttpMethod: POST
Type: AWS
Uri: !Sub "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${MyApiFunction.Arn}/invocations"
RequestTemplates:
"application/json": "
#set($inputRoot = $input.path('$'))
{
\"name\": \"$inputRoot.name\",
\"throwError\":\"$input.params('throwerror')\"
}"
The PassthroughBehavior property determines how the body of an unmapped content type will be sent to the backend service:
WHEN_NO_MATCH: The request is passed to the backend without transformation when the content type does not match any content types associated with the mapping templates.
NEVER: The request is rejected if no template matches.
WHEN_NO_TEMPLATES: The request is passed to the backend without transformation only when no mapping template is defined in the integration request.
We can use https://velocity-template-tester.onrender.com/ to test our templates.
To map headers from the method request to the backend service, we use the RequestParameters property. The headers must also be defined in the method request.
MyMethod:
Type: AWS::ApiGateway::Method
Properties:
ResourceId: !Ref MyResource
RestApiId: !Ref MyApi
AuthorizationType: NONE
HttpMethod: POST
RequestParameters:
method.request.header.version: true
MethodResponses:
- StatusCode: '200'
ResponseParameters:
method.response.header.version: true
method.response.header.id: true
- StatusCode : '500'
ResponseParameters:
method.response.header.version: true
Integration:
PassthroughBehavior: WHEN_NO_TEMPLATES
IntegrationHttpMethod: POST
Type: AWS
Uri: !Sub "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${MyApiFunction.Arn}/invocations"
RequestTemplates:
"application/json": "
#set($inputRoot = $input.path('$'))
{
\"name\": \"$inputRoot.name\",
\"throwError\":\"$input.params('throwerror')\"
}"
RequestParameters:
integration.request.header.version: method.request.header.version
The headers can come from the method request or static values. You can find more information here.
Integration Response
Now, let's check the IntegrationResponses property, which specifies how to handle the response from the backend service. We can define multiple records under this property, each identified by the StatusCode property. These status codes must match the ones defined in the method response section. Every item has ResponseTemplates and ResponseParameters properties to map the body and headers, using the same rules we discussed earlier.
The SelectionPattern property helps us match an integration response set up with a specific response from the backend service. An empty value is considered the default mapping and will be evaluated last. When the backend service is an HTTP endpoint or AWS service, this pattern is evaluated against the response status code. An exception is the Lambda functions, where error messages always appear in the errorMessage field in the response, so we match against that.
MyMethod:
Type: AWS::ApiGateway::Method
Properties:
ResourceId: !Ref MyResource
RestApiId: !Ref MyApi
AuthorizationType: NONE
HttpMethod: POST
RequestParameters:
method.request.header.version: true
MethodResponses:
- StatusCode: '200'
ResponseParameters:
method.response.header.version: true
method.response.header.id: true
- StatusCode : '500'
ResponseParameters:
method.response.header.version: true
Integration:
PassthroughBehavior: WHEN_NO_TEMPLATES
IntegrationHttpMethod: POST
Type: AWS
Uri: !Sub "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${MyApiFunction.Arn}/invocations"
RequestTemplates:
"application/json": "
#set($inputRoot = $input.path('$'))
{
\"name\": \"$inputRoot.name\",
\"throwError\":\"$input.params('throwerror')\"
}"
RequestParameters:
integration.request.header.version: method.request.header.version
IntegrationResponses:
- StatusCode: '200'
ResponseTemplates:
"application/json": "
#set($inputRoot = $input.path('$'))
{
\"petId\": \"$inputRoot.PetId\"
}"
ResponseParameters:
method.response.header.version: "'v1'"
method.response.header.id: integration.response.body.PetId
- StatusCode: '500'
SelectionPattern: ".*An error was thrown.*"
ResponseTemplates:
"application/json": "
#set($inputRoot = $input.path('$'))
{
\"error\": \"$inputRoot.errorType\"
}"
ResponseParameters:
method.response.header.version: "'v1'"
Run the following commands to deploy the resources to AWS:
sam build
sam deploy --guided
aws apigateway create-deployment --rest-api-id [RestApiId] --stage-name prod --description "my stage"
You can find the final code here. Thanks, and happy coding.
