aws-openapigateway-lambda
Reference Documentation: | https://docs.aws.amazon.com/solutions/latest/constructs/ |
Language | Package |
---|---|
|
|
|
|
|
|
Overview
This AWS Solutions Construct implements an Amazon API Gateway REST API defined by an OpenAPI specification file connected to an AWS Lambda function.
Here is a minimal deployable pattern definition.
NOTE The referenced openapi/apiDefinition.yaml
openapi definition
file and messages-lambda
lambda package directory for the three code
samples below can both be found under this constructs test
folder
(<repository_root>/source/patterns/@aws-solutions-constructs/aws-openapigateway-lambda/test
)
Pattern Construct Props
Name | Type | Description |
---|---|---|
apiGatewayProps? |
Optional user-provided props to override the default props for the API. |
|
apiDefinitionBucket? |
S3 Bucket where the OpenAPI spec file is located. When specifying this
property, |
|
apiDefinitionKey? |
|
S3 Object name of the OpenAPI spec file.
When specifying this property, |
apiDefinitionAsset? |
Local file asset of the OpenAPI spec file. |
|
apiDefinitionJson? |
any |
OpenAPI specification represented in a JSON object to be embedded in the CloudFormation template. IMPORTANT - Including the spec in the template introduces a risk of the template growing too big, but there are some use cases that require an embedded spec. Unless your use case explicitly requires an embedded spec you should pass your spec as an S3 asset. |
apiIntegrations |
|
One or more key-value pairs
that contain an id for the api integration and either an existing lambda
function or an instance of the LambdaProps. Please see the
|
logGroupProps? |
User provided props to override the default props for for the CloudWatchLogs LogGroup. |
Pattern Properties
Name | Type | Description |
---|---|---|
apiLambdaFunctions |
|
Returns an array of
ApiLambdaFunction objects, where each has an |
apiGateway |
Returns an instance of the API Gateway REST API created by the pattern. |
|
apiGatewayCloudWatchRole? |
Returns an instance of the iam.Role created by the construct for API Gateway for CloudWatch access. |
|
apiGatewayLogGroup |
Returns an instance of the LogGroup created by the construct for API Gateway access logging to CloudWatch. |
Interfaces defined by this construct
ApiIntegration
Maps a Lambda function to the id string used as a
placeholder in the OpenAPI spec. The type has a required property, id
,
and two optional properties existingLambdaObj
, and
lambdaFunctionProps
. The id
property is used to map the
corresponding lambda function being defined with the placeholder string
in the OpenAPI template file, and is not a CDK construct ID. Exactly one
of existingLambdaObj
or lambdaFunctionProps
must be specified or the
construct will throw an error. The existingLambaObj
property will
accept a lambda.Function object OR a lambda.Alias object. The property
ApiIntegrations
is an array of this interface and is a required
property when launching this construct.
ApiLambdaFunction
This interface returns the Lambda objects used when
launching the construct. The id
property will always be set, if an
existing function was provided in the props or this construct created a
new Lambda function, then that function will be in the lambdaFunction
property. If a Lambda Alias was provided in the props, then that value
will be specified in the functionAlias
property. At no time will
lambdaFunction
and functionAlias
be set on the same
ApiLambdaFunction object. The construct exposes an array of these
objects as a property.
Overview of how the OpenAPI file transformation works
This construct automatically transforms an incoming OpenAPI Definition
(residing locally or in S3) by auto-populating the uri
fields of the
x-amazon-apigateway-integration
integrations with the resolved value
of the backing lambda functions. It does so by allowing the user to
specify the apiIntegrations
property and then correlates it with the
api definition.
Looking at an example - a user creates an instantiation of
apiIntegrations
that specifies one integration named MessagesHandler
that passes in a set of lambda.FunctionProps
and a second integration
named PhotosHandler
that passes in an existing lambda.Function
:
const apiIntegrations: ApiIntegration[] = [ { id: 'MessagesHandler', lambdaFunctionProps: { runtime: lambda.Runtime.NODEJS_20_X, handler: 'index.handler', code: lambda.Code.fromAsset(`${__dirname}/messages-lambda`), } }, { id: 'PhotosHandler', existingLambdaObj: new lambda.Function(this, 'PhotosLambda', { runtime: lambda.Runtime.NODEJS_20_X, handler: 'index.handler', code: lambda.Code.fromAsset(`${__dirname}/photos-lambda`), }) } ]
And a corresponding api definition with GET
and POST
methods on a
/messages
resource and a GET
method on a /photos
resource.
openapi: "3.0.1" info: title: "api" version: "2023-02-20T20:46:08Z" paths: /messages: get: x-amazon-apigateway-integration: httpMethod: "POST" uri: MessagesHandler passthroughBehavior: "when_no_match" type: "aws_proxy" post: x-amazon-apigateway-integration: httpMethod: "POST" uri: MessagesHandler passthroughBehavior: "when_no_match" type: "aws_proxy" /photos: get: x-amazon-apigateway-integration: httpMethod: "POST" uri: PhotosHandler passthroughBehavior: "when_no_match" type: "aws_proxy"
When the construct is created or updated, it will overwrite the
MessagesHandler
string with the fully resolved lambda proxy uri of the
MessagesHandlerLambdaFunction
, e.g.,
arn:${Aws.PARTITION}:apigateway:${Aws.REGION}:lambda:path/2015-03-31/functions/${messagesLambda.functionArn}/invocations
,
and similarly for the PhotosHandler
string and
PhotosHandlerLambdaFunction
, resulting in a valid OpenAPI spec file
that is then passed to the SpecRestApi
construct.
For more information on specifying an API with OpenAPI, please see the
OpenAPI Specification
Default settings
Out of the box implementation of the Construct without any override will set the following defaults:
Amazon API Gateway
-
Deploy an edge-optimized API endpoint
-
Enable CloudWatch logging for API Gateway
-
Configure least privilege access IAM role for API Gateway
-
Enable X-Ray Tracing
AWS Lambda Function
-
Configure limited privilege access IAM roles for Lambda functions
-
Enable reusing connections with Keep-Alive for NodeJs Lambda functions
-
Enable X-Ray Tracing
-
Set Environment Variables
-
AWS_NODEJS_CONNECTION_REUSE_ENABLED (for Node 10.x and higher functions)
-
Architecture

Github
Go to the Github repo