@aws-cdk/aws-apigateway

CDK Construct Library for Amazon API Gateway

Amazon API Gateway is a fully managed service that makes it easy for developers to publish, maintain, monitor, and secure APIs at any scale. Create an API to access data, business logic, or functionality from your back-end services, such as applications running on Amazon Elastic Compute Cloud (Amazon EC2), code running on AWS Lambda, or any web application.

Defining APIs

APIs are defined as a hierarchy of resources and methods. addResource and addMethod can be used to build this hierarchy. The root resource is api.root.

For example, the following code defines an API that includes the following HTTP endpoints: ANY /, GET /books, POST /books, GET /books/{book_id}, DELETE /books/{book_id}.

const api = new apigateway.RestApi(this, 'books-api');

api.root.addMethod('ANY');

const books = api.root.addResource('books');
books.addMethod('GET');
books.addMethod('POST');

const book = books.addResource('{book_id}');
book.addMethod('GET');
book.addMethod('DELETE');

Integration Targets

Methods are associated with backend integrations, which are invoked when this method is called. API Gateway supports the following integrations:

• MockIntegration - can be used to test APIs. This is the default integration if one is not specified.
• LambdaIntegration - can be used to invoke an AWS Lambda function.
• AwsIntegration - can be used to invoke arbitrary AWS service APIs.
• HttpIntegration - can be used to invoke HTTP endpoints.

The following example shows how to integrate the GET /book/{book_id} method to an AWS Lambda function:

const getBookHandler = new lambda.Function(...);
const getBookIntegration = new apigateway.LambdaIntegration(getBookHandler);
book.addMethod('GET', getBookIntegration);

Integration options can be optionally be specified:

const getBookIntegration = new apigateway.LambdaIntegration(getBookHandler, {
  contentHandling: apigateway.ContentHandling.ConvertToText, // convert to base64
  credentialsPassthrough: true, // use caller identity to invoke the function
});

Method options can optionally be specified when adding methods:

book.addMethod('GET', getBookIntegration, {
  authorizationType: apigateway.AuthorizationType.IAM,
  apiKeyRequired: true
});

Default Integration and Method Options

The defaultIntegration and defaultMethodOptions properties can be used to configure a default integration at any resource level. These options will be used when defining method under this resource (recursively) with undefined integration or options.

If not defined, the default integration is MockIntegration. See reference documentation for default method options.

The following example defines the booksBackend integration as a default integration. This means that all API methods that do not explicitly define an integration will be routed to this AWS Lambda function.

const booksBackend = new apigateway.LambdaIntegration(...);
const api = new apigateway.RestApi(this, 'books', {
  defaultIntegration: booksBackend
});

const books = new api.root.addResource('books');
books.addMethod('GET');  // integrated with `booksBackend`
books.addMethod('POST'); // integrated with `booksBackend`

const book = books.addResource('{book_id}');
book.addMethod('GET');   // integrated with `booksBackend`

Deployments

By default, the RestApi construct will automatically create an API Gateway Deployment and a "prod" Stage which represent the API configuration you defined in your CDK app. This means that when you deploy your app, your API will be have open access from the internet via the stage URL.

The URL of your API can be obtained from the attribute restApi.url, and is also exported as an Output from your stack, so it's printed when you cdk deploy your app:

$ cdk deploy
...
books.booksapiEndpointE230E8D5 = https://6lyktd4lpk.execute-api.us-east-1.amazonaws.com/prod/

To disable this behavior, you can set { deploy: false } when creating your API. This means that the API will not be deployed and a stage will not be created for it. You will need to manually define a apigateway.Deployment and apigateway.Stage resources.

Use the deployOptions property to customize the deployment options of your API.

The following example will configure API Gateway to emit logs and data traces to AWS CloudWatch for all API calls:

By default, an IAM role will be created and associated with API Gateway to allow it to write logs and metrics to AWS CloudWatch cloudWatchRole is set to false.

const api = new apigateway.RestApi(this, 'books', {
  deployOptions: {
    loggingLevel: apigateway.MethodLoggingLevel.Info,
    dataTraceEnabled: true
  }
})

Deeper dive: invalidation of deployments

API Gateway deployments are an immutable snapshot of the API. This means that we want to automatically create a new deployment resource every time the API model defined in our CDK app changes.

In order to achieve that, the AWS CloudFormation logical ID of the AWS::ApiGateway::Deployment resource is dynamically calculated by hashing the API configuration (resources, methods). This means that when the configuration changes (i.e. a resource or method are added, configuration is changed), a new logical ID will be assigned to the deployment resource. This will cause CloudFormation to create a new deployment resource.

By default, old deployments are deleted. You can set retainDeployments: true to allow users revert the stage to an old deployment manually.

Missing Features

See awslabs/aws-cdk#723 for a list of missing features.

---

This module is part of the AWS Cloud Development Kit project.

Changelog

0.9.2 (2018-09-20)

NOTICE: This release includes a framework-wide breaking change which changes the type of all the string resource attributes across the framework. Instead of using strong-types that extend cdk.Token (such as QueueArn, TopicName, etc), we now represent all these attributes as normal strings, and codify the tokens into the string (using the feature introduced in #168).

Furthermore, the cdk.Arn type has been removed. In order to format/parse ARNs, use the static methods on cdk.ArnUtils.

See motivation and discussion in #695.

Breaking Changes

• cfn2ts: use stringified tokens for resource attributes instead of strong types (#712) (6508f78), closes #518 #695 #744
• aws-dynamodb: Attribute type for keys, changes the signature of the addPartitionKey and addSortKey methods to be consistent across the board. (#720) (e6cc189)
• aws-codebuild: fix typo "priviledged" -> "privileged

Bug Fixes

• assets: can't use multiple assets in the same stack (#725) (bba2e5b), closes #706
• aws-codebuild: typo in BuildEnvironment "priviledged" -> "privileged (#734) (72fec36)
• aws-ecr: fix addToResourcePolicy (#737) (eadbda5)
• aws-events: ruleName can now be specified (#726) (a7bc5ee), closes #708
• aws-lambda: jsii use no long requires 'sourceAccount' (#728) (9e7d311), closes #714
• aws-s3: remove policy argument (#730) (a79190c), closes #672
• cdk: "cdk init" java template is broken (#732) (281c083), closes #711 awslabs/jsii#233

Features

• aws-apigateway: new API Gateway Construct Library (#665) (b0f3857)
• aws-cdk: detect presence of EC2 credentials (#724) (8e8c295), closes #702 #130
• aws-codepipeline: make the Stage insertion API in CodePipeline more flexible (#460) (d182818)
• aws-codepipeline: new "Pipeline#addStage" convenience method (#647) (25c9fa0)
• aws-rds: add support for parameter groups (#729) (2541508), closes #719
• docs: add documentation for CDK toolkit plugings (#733) (965b918)
• dependencies: upgrade to jsii 0.7.6