API Gateway V2 - Http API

Amazon API Gateway invokes your function synchronously with an event that contains a JSON representation of the HTTP request.

Event driven, synchronously invokes

Limits

Lambda specific hard limitations

• Payload limit of 6mb for the Lambda
• Maximum timeout of 30 seconds

NOTE: General limits and differents from Rest API

Large things missing IMO is AWS X-Ray, Usage Plans and API Keys

• Choosing between HTTP APIs and REST APIs
• HTTP API quotas

Request

Getting the correlation id

JSON path to correlation id: requestContext.requestId

Generating sample events

Via AWS SAM CLI you can generate sample events

sam local generate-event apigateway http-api-proxy

Request Stucture format 2.0

Note

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.

Http api format 2.0

{
  "version": "2.0",
  "routeKey": "$default",
  "rawPath": "/my/path",
  "rawQueryString": "parameter1=value1&parameter1=value2&parameter2=value",
  "cookies": [
    "cookie1",
    "cookie2"
  ],
  "headers": {
    "Header1": "value1",
    "Header2": "value1,value2"
  },
  "queryStringParameters": {
    "parameter1": "value1,value2",
    "parameter2": "value"
  },
  "requestContext": {
    "accountId": "123456789012",
    "apiId": "api-id",
    "authentication": {
      "clientCert": {
        "clientCertPem": "CERT_CONTENT",
        "subjectDN": "www.example.com",
        "issuerDN": "Example issuer",
        "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
        "validity": {
          "notBefore": "May 28 12:30:02 2019 GMT",
          "notAfter": "Aug  5 09:36:04 2021 GMT"
        }
      }
    },
    "authorizer": {
      "jwt": {
        "claims": {
          "claim1": "value1",
          "claim2": "value2"
        },
        "scopes": [
          "scope1",
          "scope2"
        ]
      }
    },
    "domainName": "id.execute-api.us-east-1.amazonaws.com",
    "domainPrefix": "id",
    "http": {
      "method": "POST",
      "path": "/my/path",
      "protocol": "HTTP/1.1",
      "sourceIp": "192.168.0.1/32",
      "userAgent": "agent"
    },
    "requestId": "id",
    "routeKey": "$default",
    "stage": "$default",
    "time": "12/Mar/2020:19:03:58 +0000",
    "timeEpoch": 1583348638390
  },
  "body": "{\"message\": \"hello world\", \"username\": \"tom\"}",
  "pathParameters": {
    "parameter1": "value1"
  },
  "isBase64Encoded": false,
  "stageVariables": {
    "stageVariable1": "value1",
    "stageVariable2": "value2"
  }
}

Request Stucture format 1.0

Note

This is the same format as API Gateway V1 - Rest API

Http api format 1.0

{
  "version": "1.0",
  "resource": "/my/path",
  "path": "/my/path",
  "httpMethod": "GET",
  "headers": {
    "header1": "value1",
    "header2": "value2"
  },
  "multiValueHeaders": {
    "header1": [
      "value1"
    ],
    "header2": [
      "value1",
      "value2"
    ]
  },
  "queryStringParameters": {
    "parameter1": "value1",
    "parameter2": "value"
  },
  "multiValueQueryStringParameters": {
    "parameter1": [
      "value1",
      "value2"
    ],
    "parameter2": [
      "value"
    ]
  },
  "requestContext": {
    "accountId": "123456789012",
    "apiId": "id",
    "authorizer": {
      "claims": null,
      "scopes": null
    },
    "domainName": "id.execute-api.us-east-1.amazonaws.com",
    "domainPrefix": "id",
    "extendedRequestId": "request-id",
    "httpMethod": "GET",
    "identity": {
      "accessKey": null,
      "accountId": null,
      "caller": null,
      "cognitoAuthenticationProvider": null,
      "cognitoAuthenticationType": null,
      "cognitoIdentityId": null,
      "cognitoIdentityPoolId": null,
      "principalOrgId": null,
      "sourceIp": "IP",
      "user": null,
      "userAgent": "user-agent",
      "userArn": null,
      "clientCert": {
        "clientCertPem": "CERT_CONTENT",
        "subjectDN": "www.example.com",
        "issuerDN": "Example issuer",
        "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1",
        "validity": {
          "notBefore": "May 28 12:30:02 2019 GMT",
          "notAfter": "Aug  5 09:36:04 2021 GMT"
        }
      }
    },
    "path": "/my/path",
    "protocol": "HTTP/1.1",
    "requestId": "id=",
    "requestTime": "04/Mar/2020:19:15:17 +0000",
    "requestTimeEpoch": 1583349317135,
    "resourceId": null,
    "resourcePath": "/my/path",
    "stage": "$default"
  },
  "pathParameters": null,
  "stageVariables": null,
  "body": "Hello from Lambda!",
  "isBase64Encoded": false
}

Response

Common response fields

isBase64Encoded (Boolean, defaults as false)

Whether the response body is a base64 encoded string

statusCode (Int, required)

The http response code

headers (Object)

Map of http headers

body (String)

Response body

Base64 encoded response example

{
    "isBase64Encoded": true,
    "statusCode": 200,
    "headers": {
        "Content-Type": "application/json",
        "Content-Encoding": "gzip"
    },
    "body": "H4sIAAAAAAACE6tWKkktLlGyUlAqS8wpTVWqBQCJ88g/EQAAAA=="
}

Response for format 2.0

Format 2.0 specific fields, a replacement for multiValueHeaders from format 1.0

cookies (Array of strings)

Dedeicated field for cookies

Lambda function response for format 2.0

{
    "cookies" : ["cookie1", "cookie2"],
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headername": "headervalue", ... },
    "body": "Hello from Lambda!"
}

Response for format 1.0

Format 1.0 specific fields

multiValueHeaders (Object)

Can be optionally included, useful for sending cookies with multiple Set-Cookie header

Lambda function response for format 1.0

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headername": "headervalue", ... },
    "multiValueHeaders": { "headername": ["headervalue", "headervalue2", ...], ... },
    "body": "..."
}

Resources

Typed Lambda handlers by Language

• Python - data class and parser - Pip aws-lambda-powertools
• Typescript - api-gateway-proxy.d.ts - NPM @types/aws-lambda
• Go - ApiGatewayEvent typing - Go github.com/aws/aws-lambda-go/events
• DoNet - APIGatewayEvents data classes - NuGet Amazon.Lambda.APIGatewayEvents
• Rust - apigw/mod.rs traits - Cargo aws_lambda_events
• Java - APIGatewayV2HTTPEvent data classes - Maven aws-lambda-java-events
• PHP - typing - Composer bref/bref

Event Handlers by Language

• AWS Lambda Powertools Python - APIGatewayHttpResolver
• PHP Bref for webapps
• Java - Serverless Java container - Makes it easy to run Java applications written with frameworks such as Spring, Spring Boot, Apache Struts, Jersey, or Spark in AWS Lambda
• AWS Lambda Adapter - A tool to run any web applications on AWS Lambda. Written in Rust.

Code examples

Example handler for API Gateway V2 (Http API), payload format v2

example on how we can handle the /hello path.

from aws_lambda_powertools import Logger, Tracer
from aws_lambda_powertools.logging import correlation_paths
from aws_lambda_powertools.event_handler import APIGatewayHttpResolver

tracer = Tracer()
logger = Logger()
app = APIGatewayHttpResolver()

@app.get("/hello")
@tracer.capture_method
def get_hello_universe():
    return {"message": "hello universe"}

# You can continue to use other utilities just as before
@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_HTTP)
@tracer.capture_lambda_handler
def lambda_handler(event, context):
    return app.resolve(event, context)

Documention

• Working with AWS Lambda proxy integrations for HTTP APIs
• Using AWS Lambda with Amazon API Gateway