Working with Amazon Lambda proxy integrations for HTTP APIs
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 Creating 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.
The following examples show the structure of each payload format version.
Note
Header names are lowercased.
Format 2.0
doesn't have multiValueHeaders
or
multiValueQueryStringParameters
fields. Duplicate headers are combined with commas and included
in the headers
field. Duplicate query strings are combined with commas and included in the
queryStringParameters
field.
Format 2.0
includes a new cookies
field. All cookie headers in the request are
combined with commas and added to the cookies
field. In the response to the client, each cookie
becomes a set-cookie
header.
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!
" }