Skip to main content

Using an existing API

Start with Getting Started if you do not already have an API. LambdaApi can also add the discovered routes to an API construct that already exists in the same CDK stack.

Existing REST API​

Pass an apigateway.RestApi through api. LambdaApi recognizes the REST family from the supplied object, so api_type can be omitted:

from aws_cdk import Stack, aws_apigateway as apigateway, aws_lambda as lambda_
from constructs import Construct
from lambda_api_decorators_cdk import LambdaApi, LambdaApiConfig


class RestStack(Stack):
    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        existing_api = apigateway.RestApi(self, "ExistingRestApi")
        self.api = LambdaApi(
            self,
            "Handlers",
            lambda_path="lambdas",
            api=existing_api,
            config=LambdaApiConfig(default_runtime="python3.14"),
        )

The same construct can use an imported REST API. The imported API must provide the REST interface and root resource expected by the CDK construct:

existing_api = apigateway.RestApi.from_rest_api_attributes(
    self,
    "ImportedRestApi",
    rest_api_id="api-id",
    root_resource_id="root-id",
)

Use that value as api in the previous LambdaApi call. In both cases the API object is reused; LambdaApi does not create another REST API.

Existing HTTP API​

An existing concrete apigatewayv2.HttpApi is also inferred as HTTP:

from aws_cdk import Stack, aws_apigatewayv2 as apigatewayv2, aws_lambda as lambda_
from constructs import Construct
from lambda_api_decorators_cdk import ApiType, LambdaApi, LambdaApiConfig


class HttpStack(Stack):
    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        existing_api = apigatewayv2.HttpApi(self, "ExistingHttpApi")
        self.api = LambdaApi(
            self,
            "Handlers",
            lambda_path="lambdas",
            api=existing_api,
            config=LambdaApiConfig(default_runtime="python3.14"),
        )

You may also make the inferred choice explicit with api_type=ApiType.HTTP. The value must agree with the supplied API. For example, a REST API combined with api_type=ApiType.HTTP, or an HTTP API combined with api_type=ApiType.REST, raises ValueError before route construction.

There is a current limitation for imported HTTP APIs: the wrapper accepts an instance of the concrete apigatewayv2.HttpApi class. The object returned by apigatewayv2.HttpApi.from_http_api_attributes(...) is an imported interface object rather than that concrete class, so the current type check rejects it with TypeError. This is a verified implementation limitation, not a claim about every API Gateway import mechanism.

What is created and what is reused?​

The API and routes are CDK resources in the stack where LambdaApi runs. A new RestApi or HttpApi is created when api is omitted. When api is provided, that API is reused—whether it was created earlier in the same stack or represented by a supported imported object. The discovered Lambda functions and their integrations are still built as part of the current LambdaApi construct.

See the LambdaApi API reference for the complete constructor contract.