{"id":8851,"library":"aws-cdk-aws-apigateway","title":"AWS CDK API Gateway Construct Library (v1)","description":"The AWS Cloud Development Kit (CDK) Construct Library for AWS::ApiGateway provides high-level constructs to define API Gateway resources programmatically. This entry focuses on version 1.204.0, part of the CDK v1 series, which receives regular updates, but has a successor in CDK v2 with different packaging.","status":"active","version":"1.204.0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk.git","tags":["aws","cdk","apigateway","infrastructure-as-code","cloud-development-kit"],"install":[{"cmd":"pip install aws-cdk.aws-apigateway==1.204.0 aws-cdk.core==1.204.0","lang":"bash","label":"Install for v1"}],"dependencies":[{"reason":"Core CDK library, required for all CDK applications.","package":"aws-cdk.core","optional":false}],"imports":[{"note":"Commonly imported with an alias for brevity and to distinguish from V2 imports.","wrong":"from aws_cdk.aws_apigateway import RestApi","symbol":"aws_apigateway","correct":"from aws_cdk import aws_apigateway as apigw"},{"note":"After importing `aws_cdk.aws_apigateway as apigw`, constructs are accessed via the alias.","wrong":"RestApi(...)","symbol":"RestApi","correct":"apigw.RestApi(...)"}],"quickstart":{"code":"import os\nfrom aws_cdk import (\n    core,\n    aws_apigateway as apigw,\n    aws_lambda as lambda_,\n)\n\nclass MyApiStack(core.Stack):\n    def __init__(self, scope: core.Construct, id: str, **kwargs) -> None:\n        super().__init__(scope, id, **kwargs)\n\n        # Define a Lambda function to integrate with API Gateway\n        hello_function = lambda_.Function(\n            self, \"HelloFunction\",\n            runtime=lambda_.Runtime.PYTHON_3_9,\n            handler=\"index.handler\",\n            code=lambda_.Code.from_inline(\"def handler(event, context): return {'statusCode': 200, 'body': 'Hello from Lambda!'}\")\n        )\n\n        # Create a REST API\n        api = apigw.RestApi(\n            self, \"MySimpleApi\",\n            rest_api_name=\"MySimpleApi\",\n            description=\"A simple API Gateway example backed by Lambda.\",\n            deploy=True, # Automatically creates a default deployment and stage\n            deploy_options=apigw.StageOptions(\n                stage_name=\"dev\"\n            )\n        )\n\n        # Add a GET method to the root path, integrating with the Lambda function\n        api.root.add_method(\n            \"GET\",\n            apigw.LambdaIntegration(hello_function)\n        )\n\napp = core.App()\nMyApiStack(app, \"MyApiGatewayStack\")\napp.synth()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All v1 versions (1.x.x) when migrating to v2 (2.x.x)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All v1 versions"},{"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')`.","message":"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.","severity":"gotcha","affected_versions":"All v1 versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All v1 versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The `aws-cdk.aws-apigateway` library is not installed or the Python environment is incorrect.","error":"ModuleNotFoundError: No module named 'aws_cdk.aws_apigateway'"},{"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', ...)`.","cause":"You are attempting to create two Constructs with the same ID within the same parent scope (e.g., the same Stack).","error":"A Construct with scope 'MyApiGatewayStack' and id 'MySimpleApi' already exists."},{"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.","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.","error":"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:..."},{"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.","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`.","error":"TypeError: Expected scope to be an instance of Construct, got <class 'aws_cdk.core.App'>"}]}