Configuration model

LambdaApiConfig is the high-level place to define values shared by one or more LambdaApi constructs. It is resolved before the builder creates each discovered Lambda. The constructor defaults are None for optional scalar values, empty for common collections and named registries, and no default authorizer. When a value remains unset, the underlying CDK construct can apply its own default.

The model has four useful layers:

1. Defaults apply to every discovered function: runtime, timeout, memory, VPC, and execution role.
2. Common values are copied into every function: layers, security groups, and environment variables.
3. Named registries map logical names to CDK resources or values, such as DynamoDB tables, S3 buckets, authorizers, roles, layers, VPCs, security groups, and environments.
4. Decorators select or override those values for one handler. For example, @runtime("python3.14") selects a registered runtime alias and @environment("STAGE") selects a named environment value.

Resolution and precedence

The current builder behavior is observable in its tests and follows this pattern:

Declaration	Effective behavior
Scalar default → scalar decorator	The decorator replaces the default (runtime, timeout, memory_size, role, vpc, name, or description)
Common layers/security groups → handler decorator	Common values remain and selected values are appended
Common environment → handler decorator	The maps are merged; a selected key replaces the common value for that key
Named registry → decorator alias	The alias is looked up; an unknown key raises an error

HTTP, permission, and grant declarations are resolved separately as route and access metadata. A route authorizer inherits the configured default unless the handler uses @authorizer(...) or @public.

default_runtime="python3.14" is the configuration default and @runtime("python3.14") overrides it for one handler. The alias resolves to the matching CDK runtime.

from aws_cdk import aws_lambda as lambda_
from lambda_api_decorators import GET, runtime
from lambda_api_decorators_cdk import LambdaApiConfig

config = LambdaApiConfig(default_runtime="python3.14")

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

The complete methods and supported registries are in the LambdaApiConfig API reference; the focused usage patterns are in Lambda configuration.

Reusing a configuration object

The current tests confirm isolation between builds that reuse one LambdaApiConfig: each LambdaApi receives a fresh internal builder and fresh mutable containers, while the referenced CDK resource objects retain their identity. A change to one builder's copied layers, security groups, environment, or registries therefore does not mutate the other builder's configuration. This does not make CDK resource objects themselves copies.