LambdaApi

LambdaApi is the recommended CDK interface. It discovers decorated handlers, creates or uses an API Gateway API, and delegates configuration to LambdaApiConfig.

Constructor

Class signature: LambdaApi(scope, construct_id, *, lambda_path: str, source_layout: SourceLayout = SourceLayout.ROOT, layers_path: Optional[str] = None, api = None, api_type: Optional[ApiType] = None, config: Optional[LambdaApiConfig] = None, endpoint_type: Optional[apigateway.EndpointType] = None)

Bases: Construct

Example:

from aws_cdk import Stack
from constructs import Construct
from lambda_api_decorators_cdk import LambdaApi, LambdaApiConfig

class ApiStack(Stack):
    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)
        self.api = LambdaApi(
            self, "Api", lambda_path="lambdas", config=LambdaApiConfig()
        )

HTTP API example:

from lambda_api_decorators_cdk import ApiType, LambdaApi, SourceLayout

api = LambdaApi(
    self,
    "HttpApi",
    lambda_path="lambdas",
    api_type=ApiType.HTTP,
    source_layout=SourceLayout.SERVICE,
    layers_path="layers",
)

Parameters:

• scope (Construct) – CDK construct scope.

• construct_id (str) – Identifier for this construct.

• lambda_path (str) – Path to the directory containing discovered handlers.

• source_layout (SourceLayout) – SourceLayout.ROOT or SourceLayout.SERVICE. Default: SourceLayout.ROOT.

• layers_path (Optional[str]) – Optional directory for layer source discovery. Default: None.

• api (Optional[Union[apigateway.IRestApi, apigatewayv2.HttpApi]]) – Existing REST IRestApi or HttpApi. If omitted, an API is created.

• api_type (Optional[ApiType]) – ApiType.REST or ApiType.HTTP. Default: inferred from api, or REST when no API is supplied.

• config (Optional[LambdaApiConfig]) – Configuration object for defaults and registries. Default: a new empty LambdaApiConfig.

• endpoint_type (Optional[apigateway.EndpointType]) – Native AWS CDK REST endpoint type for an automatically created REST API. Default: None, which creates an Edge-Optimized REST API. Supported explicit values are EndpointType.EDGE and EndpointType.REGIONAL.

source_layout, api_type, and config are type-checked. A supplied API must be a REST API implementation or HttpApi; an unsupported object raises TypeError. If api and api_type identify different families, construction raises ValueError. An omitted API produces RestApi for REST and HttpApi for HTTP.

REST routes use the declarations exported by lambda-api-decorators, including ANY. HTTP routes use the explicit GET, POST, PUT, and DELETE declarations; a discovered ANY route is not mapped by the current HTTP builder.

Endpoint behavior

endpoint_type controls only an automatically created REST API. It uses the native AWS CDK aws_apigateway.EndpointType enum; IaD does not define a second endpoint enum.

API family	Configuration	Result
REST	Omitted	EDGE
REST	EndpointType.EDGE	EDGE
REST	EndpointType.REGIONAL	REGIONAL
REST	EndpointType.PRIVATE	Unsupported
HTTP API v2	Omitted	Regional
HTTP API v2	Explicit endpoint_type	Rejected
Supplied API	Omitted	Preserves caller configuration
Supplied API	Explicit endpoint_type	Rejected

For example, create a regional REST API with:

from aws_cdk import aws_apigateway as apigateway

api = LambdaApi(
    self,
    "RegionalApi",
    lambda_path="lambdas",
    endpoint_type=apigateway.EndpointType.REGIONAL,
)

EndpointType.PRIVATE is not implemented and remains a possible future extension. HTTP API v2 is regional by its API Gateway resource model and does not accept this REST-only option. When an API object is supplied, that API is owned and configured by the caller, so an explicit endpoint_type is rejected.

Attributes

api

api -> Union[apigateway.IRestApi, apigatewayv2.HttpApi] returns the supplied or created API object.

api_type

api_type -> ApiType returns the resolved API family.

See Getting Started for a complete deployable project.

When reusing an existing API, pass it through api; api_type may be omitted because the construct infers REST or HTTP from that object. Supplying a conflicting api_type raises ValueError.