AWS CDK API Gateway Construct Library (v1)

Common errors

• ModuleNotFoundError: No module named 'aws_cdk.aws_apigateway'

  cause The `aws-cdk.aws-apigateway` library is not installed or the Python environment is incorrect.
  fix Ensure the correct CDK v1 package is installed: `pip install aws-cdk.aws-apigateway==1.204.0 aws-cdk.core==1.204.0`. If using CDK v2, the import path and package name are different.

• A Construct with scope 'MyApiGatewayStack' and id 'MySimpleApi' already exists.

  cause You are attempting to create two Constructs with the same ID within the same parent scope (e.g., the same Stack).
  fix Ensure all Construct IDs (`id` argument in `Construct(scope, id, ...)`) are unique within their immediate parent's scope. For example, change one of the `apigw.RestApi(self, 'MySimpleApi', ...)` to `apigw.RestApi(self, 'MyOtherApi', ...)`.

• Error: Stack 'MyApiGatewayStack' failed to deploy: User: arn:aws:iam::xxxxxxxxxxxx:user/YourUser is not authorized to perform: apigateway:CREATE_REST_API on resource: arn:aws:apigateway:...

  cause The AWS IAM user or role used for deploying the CDK stack does not have sufficient permissions to create or manage API Gateway resources.
  fix Grant the necessary IAM permissions to the deploying identity. For full CDK deployment, a policy like `arn:aws:iam::aws:policy/AdministratorAccess` or a more granular custom policy including `apigateway:*`, `lambda:*`, `iam:*`, etc., is required.

• TypeError: Expected scope to be an instance of Construct, got <class 'aws_cdk.core.App'>

  cause You are attempting to instantiate a Construct (e.g., `apigw.RestApi`) directly under `core.App` instead of within a `core.Stack` or another `core.Construct`.
  fix Constructs like `apigw.RestApi` must be scoped to a `core.Stack` or another Composite Construct. For example, use `apigw.RestApi(self, "MyApi")` inside a `core.Stack` class, where `self` refers to the stack instance.

Warnings

• breaking This library (`aws-cdk.aws-apigateway`) is part of AWS CDK v1. AWS CDK v2 is a major rewrite with different package structures, module names (e.g., `aws_cdk.aws_apigateway` is now `aws_cdk_lib.aws_apigateway`), and updated constructs. Migrating from v1 to v2 requires significant code changes.
  Fix: For new projects, consider using CDK v2 (install `aws-cdk-lib`). For existing v1 projects, follow the official AWS CDK v2 migration guide to upgrade components gradually or maintain a v1 environment.
• gotcha All Constructs within a given scope (e.g., a Stack or another Construct) must have a unique ID. Reusing IDs will lead to synthesis or deployment errors.
  Fix: Ensure that the `id` argument for each Construct instantiation is unique within its parent scope. For example, `apigw.RestApi(self, 'MyApi')` and `apigw.RestApi(self, 'AnotherApi')` are valid, but two `RestApi(self, 'MyApi')` calls in the same scope are not.
• gotcha API Gateway requires explicit deployment and stage creation to make the API accessible. While `deploy=True` on `apigw.RestApi` creates a default deployment and stage, complex scenarios with multiple stages, custom stage variables, or external deployment triggers require manual `apigw.Deployment` and `apigw.Stage` constructs.
  Fix: For simple APIs, use `deploy=True` on `apigw.RestApi`. For advanced stage management, explicitly define `apigw.Deployment(self, 'ApiDeployment', api=api)` and `apigw.Stage(self, 'ProdStage', deployment=deployment, stage_name='prod')`.
• gotcha When integrating API Gateway with other AWS services (e.g., Lambda, SQS, Kinesis), ensure that the API Gateway execution role or the integrated resource itself has the necessary IAM permissions. While Lambda integrations often handle this automatically, other integrations might require manual IAM policy attachments.
  Fix: Explicitly grant permissions using `iam.Role` and `iam.PolicyStatement` constructs. For example, if integrating with SQS, the API Gateway execution role needs `sqs:SendMessage` permissions to the target queue.

Install

• pip install aws-cdk.aws-apigateway==1.204.0 aws-cdk.core==1.204.0 Install for v1

Imports

• aws_apigateway
  wrong:

  from aws_cdk.aws_apigateway import RestApi

  correct:

  from aws_cdk import aws_apigateway as apigw

  Commonly imported with an alias for brevity and to distinguish from V2 imports.
• RestApi
  wrong:

  RestApi(...)

  correct:

  apigw.RestApi(...)

  After importing `aws_cdk.aws_apigateway as apigw`, constructs are accessed via the alias.

Quickstart

This quickstart defines a simple AWS CDK v1 stack that creates an API Gateway REST API with a single GET endpoint. This endpoint is integrated with a Python Lambda function that returns a 'Hello from Lambda!' message. It demonstrates basic API Gateway and Lambda integration within the CDK v1 framework. Remember to run `cdk deploy` after `app.synth()` to provision resources.

import os
from aws_cdk import (
    core,
    aws_apigateway as apigw,
    aws_lambda as lambda_,
)

class MyApiStack(core.Stack):
    def __init__(self, scope: core.Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # Define a Lambda function to integrate with API Gateway
        hello_function = lambda_.Function(
            self, "HelloFunction",
            runtime=lambda_.Runtime.PYTHON_3_9,
            handler="index.handler",
            code=lambda_.Code.from_inline("def handler(event, context): return {'statusCode': 200, 'body': 'Hello from Lambda!'}")
        )

        # Create a REST API
        api = apigw.RestApi(
            self, "MySimpleApi",
            rest_api_name="MySimpleApi",
            description="A simple API Gateway example backed by Lambda.",
            deploy=True, # Automatically creates a default deployment and stage
            deploy_options=apigw.StageOptions(
                stage_name="dev"
            )
        )

        # Add a GET method to the root path, integrating with the Lambda function
        api.root.add_method(
            "GET",
            apigw.LambdaIntegration(hello_function)
        )

app = core.App()
MyApiStack(app, "MyApiGatewayStack")
app.synth()