Working with AWS 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 data 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 AWS Management Console uses the latest version
by default. If
you create a Lambda integration by using the AWS CLI, AWS CloudFormation, or an SDK,
you must specify a
payloadFormatVersion
. The supported values are 1.0
and
2.0
.
The following examples show the structure of each payload format version.
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 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!
" }