Skip to main content

Architecture

Lambda API Decorators separates declaration metadata from infrastructure construction.

Decorated Python handlers
        → AST discovery
        → configuration resolution
        → AWS CDK constructs
        → CloudFormation template
        → deployed API Gateway and Lambda resources

Package responsibilities​

lambda-api-decorators is the runtime-side package. It is CDK-free: its decorators preserve the original Python callable and record declaration metadata, while runtime helpers such as current_user read request data when the Lambda executes.

lambda-api-decorators-cdk is the infrastructure-side package. During CDK synthesis it reads Python source, discovers route declarations, resolves configuration and resource registries, then creates AWS CDK constructs for Lambda functions, API Gateway routes, integrations, and related permissions.

This separation means the deployed handler does not need to import CDK. CDK code runs while the stack is synthesized; the handler runs later in AWS when a request invokes the Lambda. The synthesized result is a CloudFormation template, which AWS uses to create or update the deployed resources.

The same separation applies to installation scopes: put lambda-api-decorators-cdk in the CDK application's dependencies and put lambda-api-decorators in the Lambda source's dependencies. They do not need to be installed together in one environment.

Public construction interfaces​

LambdaApi is the recommended high-level interface. It owns or accepts an API, selects REST or HTTP API behavior, receives lambda_path, and delegates discovery and build work to an internal builder. REST is the default when no API type or API is provided.

LambdaApiConfig is the configuration model used by LambdaApi. It holds defaults, common values, custom named registries, and CDK resource references before the build starts.

ResourceBuilder is the advanced, lower-level API. Use it when direct control over the API root or build lifecycle is needed; new code should generally start with LambdaApi.

For a practical deployment, see Getting Started, and for route choices see REST and HTTP APIs.