Lambda configuration

Use LambdaApi with LambdaApiConfig to configure the functions discovered below lambda_path. This is the recommended path for both REST and HTTP APIs; see Getting Started for the smallest complete project.

Defaults that affect every function

Pass CDK objects and values to LambdaApiConfig for defaults. The library passes these options to every generated PythonFunction unless a handler decorator overrides the option:

from aws_cdk import Duration, aws_lambda as lambda_
from lambda_api_decorators_cdk import LambdaApi, LambdaApiConfig

config = LambdaApiConfig(
    default_runtime="python3.14",
    timeout=Duration.seconds(20),
    memory_size=512,
    role=execution_role,
    common_environment={"STAGE": "prod"},
)

api = LambdaApi(self, "Api", lambda_path="lambdas", config=config)

default_runtime, timeout, memory_size, default_role, and the constructor's common_environment are defaults for all discovered functions. An omitted default is passed as None, allowing the CDK construct to apply its own default. The role must be an IAM role object; the decorator selects a registered role alias, rather than accepting a role object in handler source.

For mutable configuration, the public setters are set_default_runtime, set_default_timeout, set_default_memory_size, set_default_vpc, and set_default_role. Common environment is constructor-only; layers and security groups have corresponding add_common_* methods described in the layers and VPC guide.

Handler-specific decorators

The CDK-free package exports all of these decorators from lambda_api_decorators:

from lambda_api_decorators import (
    GET, description, environment, memory_size, name, role, runtime, timeout,
)

@GET("/fast")
@runtime("python3.13")
@timeout(10)
@memory_size(1024)
@name("fast-handler")
@description("Low-latency handler")
@environment("STAGE")
@role("special-role")
def fast(event, context):
    return {"statusCode": 200, "body": "ok"}

These declarations affect only the decorated handler. timeout is expressed in seconds and converted to Duration.seconds; environment("STAGE") looks up a registered custom value. name becomes the Lambda function_name, while description is passed through unchanged.

Registries and precedence

Custom registries are configured on the same LambdaApiConfig:

from aws_cdk import Duration, aws_lambda as lambda_

config = LambdaApiConfig(
    default_runtime="python3.12",
    timeout=Duration.seconds(30),
    memory_size=512,
    common_environment={"STAGE": "prod", "LOG_LEVEL": "info"},
)
config.register_role("special-role", execution_role)
config.register_environment("STAGE_OVERRIDE", {"STAGE": "canary"})

The exact current resolution rules are:

Option	Resolution
runtime	handler @runtime(key) replaces the config default; no decorator leaves it unchanged
timeout, memory, name, description, role	a handler declaration replaces the default; otherwise the default is used
environment	common entries are copied, then each selected custom entry is added or replaces the same key
layers, security groups	common entries are copied, then selected decorator entries are appended
VPC	@vpc(key) replaces the default VPC/subnet pair; no decorator leaves the pair unchanged

Repeated @layer and @security_group declarations are collected in source metadata. A missing registry key raises KeyError while building. The config creates an isolated builder snapshot for each LambdaApi, so later config changes do not mutate an already-created build.

Runtime aliases

@runtime takes a string registry key, not a CDK lambda_.Runtime object. A new The published contract documents the built-in aliases python3.10, python3.11, python3.12, python3.13, and python3.14:

@GET("/arm")
@runtime("python3.14")
def arm_handler(event, context):
    return {"statusCode": 200, "body": "ok"}

The constructor's default_runtime="python3.14" is the default alias; @runtime("python3.14") overrides it for one handler. They are distinct precedence levels.

For unusual integrations, ResourceBuilder is available as an advanced alternative.