Skip to main content

Getting Started

Build, deploy, and call a small REST API from a new AWS CDK Python project. This guide creates every file locally; you do not need to clone an example repository. The finished API serves GET /hello and returns a JSON message.

For the model behind this workflow, see Architecture and Discovery. This tutorial focuses on the deployable path; the Guides and API Reference cover focused options and symbols.

Prefer a complete project?

The maintained quickstart-rest example is available from the start if you prefer a complete project with tests. You can still follow this tutorial without cloning it.

Browse the full Examples catalog for independent, executable projects, including an HTTP API variant.

Prerequisites​

Before starting, install and configure the following on your computer:

  • Python 3.10 or later for the local CDK application.
  • Node.js, which the AWS CDK CLI requires.
  • The AWS CDK CLI.
  • The AWS CLI and AWS credentials with permission to bootstrap and deploy CDK resources.
  • Docker Desktop or Docker Engine, running and available from your terminal.

Docker is required to package the Lambda dependencies during both cdk synth and cdk deploy. The Lambda itself will use Python 3.14, even though the local CDK project only requires Python 3.10 or later.

Check the tools before you continue:

python3 --version
node --version
cdk --version
aws --version
docker version
aws sts get-caller-identity

The final command identifies the AWS account used for deployment. Configure credentials first if it fails; aws configure is one option.

Create the CDK application​

Choose a location for the project, create lambda-api-quickstart, and enter it. Then create the official Python CDK application:

mkdir lambda-api-quickstart
cd lambda-api-quickstart
cdk init app --language python

cdk init creates app.py, cdk.json, requirements.txt, and a Python package named lambda_api_quickstart. The generated stack lives at lambda_api_quickstart/lambda_api_quickstart_stack.py.

Add the Lambda API CDK construct to the project-level requirements.txt that cdk init generated. Keep the generated aws-cdk-lib and constructs lines, then add this line:

requirements.txt
lambda-api-decorators-cdk

This dependency belongs to the CDK application's environment. It is used while the stack is synthesized and is not a Lambda runtime dependency.

Create and activate a virtual environment, then install every project dependency from requirements.txt:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Add the Lambda handler​

Create a lambdas directory at the project root. Inside it, create an empty __init__.py file and a requirements.txt file containing exactly:

lambdas/requirements.txt
lambda-api-decorators

This dependency belongs to the Lambda package and is imported by the handler at runtime. The two packages intentionally live in separate dependency scopes, so the CDK environment and the Lambda bundle do not need to install both packages. CDK's packaging step installs the Lambda dependency from this file.

The file is the dependency list that CDK packages for the deployed Lambda. Now create the handler:

lambdas/hello.py
import json

from lambda_api_decorators import GET


@GET("/hello")
def lambda_handler(event, context):
    return {
        "statusCode": 200,
        "headers": {"Content-Type": "application/json"},
        "body": json.dumps({"message": "Hello, world!"}),
    }

Your project now has this relevant layout:

lambda-api-quickstart/
├── app.py
├── cdk.json
├── requirements.txt
├── lambda_api_quickstart/
│   └── lambda_api_quickstart_stack.py
└── lambdas/
    ├── __init__.py
    ├── hello.py
    └── requirements.txt

Configure the stack​

Replace the contents of lambda_api_quickstart/lambda_api_quickstart_stack.py with the following. LambdaApi discovers the decorated handler under lambdas, creates a REST API by default, and connects GET /hello to the function.

lambda_api_quickstart/lambda_api_quickstart_stack.py
from aws_cdk import CfnOutput, Stack, aws_lambda as lambda_
from constructs import Construct
from lambda_api_decorators_cdk import LambdaApi, LambdaApiConfig


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

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

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

        CfnOutput(
            self,
            "RestApiUrl",
            value=lambda_api.api.url,
        )

RestApiUrl prints the REST API base URL after deployment. Keep app.py as generated: it imports this stack class and calls app.synth().

Synthesize and deploy​

Synthesize the CloudFormation template. Docker must be running because this step bundles lambdas/requirements.txt into the Lambda asset.

cdk synth

Each AWS account and Region must be bootstrapped once before its first CDK deployment. If this account/Region has not been initialized, run:

cdk bootstrap

Then deploy the stack and approve the displayed changes:

cdk deploy

CDK prints an output named RestApiUrl. Copy its value, including its trailing slash, for the next step.

Call the API​

Replace REST_API_URL with the RestApiUrl output. Do not add a second slash before hello if the output already ends in one.

curl "REST_API_URLhello"

The response is:

{"message": "Hello, world!"}

Clean up​

When you no longer need the API, remove the deployed resources. This uses your AWS credentials and asks for confirmation:

cdk destroy

Troubleshooting​

Docker is unavailable. Start Docker and confirm docker version succeeds. CDK needs it to package the Lambda dependencies for synthesis and deployment.

AWS credentials are not configured. Run aws configure, sign in through your organization’s supported credential process, or export a supported AWS profile. Verify the active identity with aws sts get-caller-identity.

PowerShell blocks virtual-environment activation. In the current PowerShell session, run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass, then run .venv\Scripts\Activate.ps1 again. This change lasts only for that shell.

The CDK Region is not defined. Set a default Region with aws configure set region us-east-1, or set it for the current shell. Then run cdk bootstrap for that account and Region.

export AWS_DEFAULT_REGION=us-east-1