Create Amazon Lambda proxy integrations for HTTP APIs in API Gateway
A Lambda proxy integration enables you to integrate an API route with a Lambda function. When a client calls your API, API Gateway sends the request to the Lambda function and returns the function's response to the client. For examples of creating an HTTP API, see Create an HTTP API.
Payload format version
The payload format version specifies the format of the event that API Gateway sends to a Lambda integration, and how
API Gateway interprets the response from Lambda. If you don't specify a payload format version, the Amazon Web Services Management Console uses the
latest version by default. If you create a Lambda integration by using the Amazon CLI, Amazon CloudFormation, or an SDK, you must
specify a payloadFormatVersion
. The supported values are 1.0
and 2.0
.
For more information about how to set the payloadFormatVersion
, see
create-integration. For more information about
how to determine the payloadFormatVersion
of an existing integration, see get-integration
Payload format differences
The following list shows differences between the 1.0
and 2.0
payload format versions:
Format
2.0
doesn't havemultiValueHeaders
ormultiValueQueryStringParameters
fields. Duplicate headers are combined with commas and included in theheaders
field. Duplicate query strings are combined with commas and included in thequeryStringParameters
field.-
Format
2.0
hasrawPath
. If you use an API mapping to connect your stage to a custom domain name,rawPath
won't provide the API mapping value. Use format1.0
andpath
to access the API mapping for your custom domain name. Format
2.0
includes a newcookies
field. All cookie headers in the request are combined with commas and added to thecookies
field. In the response to the client, each cookie becomes aset-cookie
header.
Payload format structure
The following examples show the structure of each payload format version. All headernames are lowercased.
Lambda function response format
The payload format version determines the structure of the response that your Lambda function must return.
Lambda function response for format 1.0
With the 1.0
format version, Lambda integrations must return a response in the following
JSON format:
{ "isBase64Encoded": true|false, "statusCode": httpStatusCode, "headers": { "headername": "headervalue", ... }, "multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... }, "body": "..." }
Lambda function response for format 2.0
With the 2.0
format version, API Gateway can infer the response format for you. API Gateway makes the
following assumptions if your Lambda function returns valid JSON and doesn't return a
statusCode
:
-
isBase64Encoded
isfalse
. -
statusCode
is200
. -
content-type
isapplication/json
. -
body
is the function's response.
The following examples show the output of a Lambda function and API Gateway's interpretation.
Lambda function output | API Gateway interpretation |
---|---|
|
|
|
|
To customize the response, your Lambda function should return a response with the following format.
{ "cookies" : ["
cookie1
", "cookie2
"], "isBase64Encoded": true|false, "statusCode":httpStatusCode
, "headers": { "headername
": "headervalue
", ... }, "body": "Hello from Lambda!
" }