How do I pass data through an API Gateway REST API to a backend Lambda function or HTTP endpoint?

Short description

To configure a REST API to pass data to a backend Lambda function, use a Lambda custom integration.

To pass query string parameters to an HTTP endpoint, use an HTTP custom integration.

Important: Make sure that the input data is supplied as the integration request payload. It’s a best practice to use a mapping template to supply the payload. For more information, see Map request and response payloads between method and integration.

Resolution

Create a Lambda function to handle custom headers from your API Gateway API

1.    Open the Lambda console.

2.    Choose Create function. The Create function page opens with the Author from scratch option selected.

3.    In the Basic information pane, do the following: For Function name, enter a name that describes your function's purpose. For example: MapTemplate. For Runtime, choose Python 3.9.

4.    For Permissions, expand Change default execution role.

5.    Choose Use an existing role. A dropdown list of existing roles appears.

6.    For Existing role, choose the Lambda execution role that you created earlier.

7.    Choose Create function.

8.    From the Code tab, in Code source, replace the code in lambda_function.py with the following:

import json

def lambda_handler(event, context):
    print(event)
    return {
        'statusCode': 200,
        'body': json.dumps(event) # returning the data sent to backend lambda function as API response.
    }

9.    Choose Deploy.

For more information, see Building Lambda functions with Python.

Pass data to the backend Lambda function or HTTP endpoint

1.    Open the API Gateway console.

2.    Choose Create API.

-or-

(If this is your first time using API Gateway) A page that introduces you to the features of the service appears. In REST API, choose Build. When the Create Example API popup appears, choose OK.

3.    For Choose an API type, in the REST API pane, choose Build.

4.    In Create new API, choose New API.

5.    In Settings , do the following: For API name , enter a name that describes your API's purpose. For example: MappingTemplateTutorial. (Optional) For Description , enter a short description your API's purpose. For example, Send Data to Backend Lambda function/HTTP endpoint. For Endpoint Type , choose Regional.

6.    Choose Create API.

Configure your API's resources, integration point, and body mapping template

1.    In the API Gateway console, choose the name of the API that you created in the previous step. Your API's Resources page opens.

2.    On the Resources page, choose Actions. Then, choose Create Resource.

3.    In the New Child Resource pane, for Configure as proxy resource , select the check mark icon , and then choose Create Resource.

4.    On the /{proxy+} - ANY - Setup page, do the following:

• For Integration type, choose Lambda Function Proxy.
• For Lambda Region, choose the AWS Region that hosts your function.
• For Lambda Function, enter the function's name MappingTemplateTutorial.

Choose Save. An Add Permission to Lambda Function popup appears, choose OK.

7.    On the / {proxy+} - ANY - Method Execution page, choose Integration Request.

8.    On the / {proxy+} - ANY - Integration Request page, do the following:

• Uncheck the Use Lambda Proxy integration icon box. A Switch to Lambda integration popup appears.
• In the popup, choose OK. An Add Permission to Lambda Function popup appears. In the popup, choose OK
• Expand Mapping Templates.
• For Request body passthrough, choose When there are no templates defined (recommended).

Choose Add mapping template. For Content-Type, enter application/json. Then, choose the check mark icon.

9.    Choose the Generate template dropdown list, and then choose Method Request passthrough.

10.    In the mapping template editor, enter the following:

##  See http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html
#set($allParams = $input.params())
{
"method" : "$context.httpMethod", ## API method
"authcontext" : "$context.authorizer.stringkey", ## Optional output from Lambda Authorizers
## passthrough body
"body-json" : $input.json('$'),
## passthrough headers, querystrings and path parameters
"params" : {
#foreach($type in $allParams.keySet())
    #set($params = $allParams.get($type))
"$type" : {
    #foreach($paramName in $params.keySet())
    "$paramName" : "$util.escapeJavaScript($params.get($paramName))"
        #if($foreach.hasNext),#end
    #end
}
    #if($foreach.hasNext),#end
#end
}
}

11.    Choose Save.

12.    Choose Method Execution to come back to / {proxy+} - ANY - Method Execution page.

13.    Choose Method Response to setup valid method response.

14.    On /{proxy+} - ANY - Method Response page, Choose Add Response.

15.    For HTTP status code, enter 200. Then, choose the check mark icon.

16.    Choose Actions to Deploy API to a stage.

Deploy your API to a new stage

1.    Follow the instructions in Deploy a REST API to a stage. For more information, see Setting up a stage using the API Gateway console.

2.    In the Stage Editor pane, copy the Invoke URL to your clipboard.

REST API Invoke URL example

https://1a2bc3d456.execute-api.us-east-1.amazonaws.com/stage

Test your setup

To confirm that all data is being passed to backend Lambda function or HTTP endpoint by your API, run the following curl command:

Important: Replace https://restApiId.execute-api.region.amazonaws.com/stageName with your API's invoke URL.

curl -i --location --request POST 'https://1a2bc3d456.execute-api.us-east-1.amazonaws.com/stage/path1/path2?query1=querystring1&query2=querystring2' --header 'header1: value1' --header 'header2: value2' --header 'Content-Type: application/json' --data-raw '{"keybody":"valuebody"}'

The command output includes all data received by the backend Lambda function to the client. You can update the output message for your environment.

Note: To install curl on Windows, see Downloads on the Git website. For more information about curl, see the curl project website.

---

Related information

Tutorial: Build an API Gateway REST API with Lambda non-proxy integration

Setting up data transformations for REST APIs

How do I pass custom headers through API Gateway to a Lambda function using custom Lambda integration?