Api Gateway V1

The adapter to handle requests from AWS Api Gateway V1.

info

When an error is thrown during forwarding and the responseWithErrors option is true, we return a 500 status WITH error stack in the response.

Reducing Costs

Not sure when to use AWS ALB instead of API Gateway? See this article from Serverless Training to learn more.

About the adapter

This adapter turns every request coming from API Gateway V1 into an HTTP request to your framework.

api-gateway-v1-event-example.json

{
  "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
}

So, to add support to the above request, we must have registered the /my/path route as POST and when API Gateway sends this event, you will get:

• body: Hello from Lambda
• queryString: parameter1=value1&parameter1=value2&parameter2=value

Customizing

You can remove some base path with the stripBasePath option inside ApiGatewayV1Options.

caution

When you configure your API with some basePath like /prod, you should either send the request in the path /prod/my/path or set stripBasePath to /prod.

You can also ensure request headers are lowercase like the default behavior of Node.js http module by setting the lowercaseRequestHeaders option to true.

caution

ApiGateway may already be ensuring your headers are lowercase but it may be worth confirming in your own system as many libraries in the Node.js ecosystem will assume this lowercasing.

Usage

To add support to AWS API Gateway V1 you do the following:

index.ts

import { ServerlessAdapter } from '@h4ad/serverless-adapter';
import { ApiGatewayV1Adapter } from '@h4ad/serverless-adapter/adapters/aws';
import { DefaultHandler } from '@h4ad/serverless-adapter/handlers/default';
import app from './app';

export const handler = ServerlessAdapter.new(app)
  .setHandler(new DefaultHandler())
  // .setFramework(new ExpressFramework())
  // .setResolver(new PromiseResolver())
  .addAdapter(new ApiGatewayV1Adapter())
  // customizing:
  // .addAdapter(new ApiGatewayV1Adapter({ stripBasePath: '/prod' }))
  .build();

Transfer Encoding Chunked

API Gateway V1 currently didn't support chunked transfer, so we throw an exception when you send the transfer-encoding=chunked.

But, you can disable the exception by setting the throwOnChunkedTransfer to false in the ApiGatewayV1Options.

index.ts

new ApiGatewayV1Adapter({ throwOnChunkedTransfer: false })

The response body will be buffered without the special characters introduced by the chunked transfer keeping the body complete.