Skip to main content

Quickstart REST

The quickstart-rest project is the smallest executable example. It creates a default API Gateway REST API backed by one Lambda function and exposes GET /hello.

It is the runnable counterpart to the Getting Started tutorial. Getting Started builds the same shape file by file; this page explains the complete example without requiring the repository README.

Architecture​

The CDK app creates one QuickstartRestStack. LambdaApi discovers one decorated handler under lambdas, creates one Lambda function, and connects it to the default REST API. Because api_type is omitted, the API family is REST.

Infrastructure​

The complete quickstart_rest/quickstart_rest_stack.py is:

from aws_cdk import Stack, aws_lambda as lambda_
from constructs import Construct
from lambda_api_decorators_cdk import LambdaApi, LambdaApiConfig


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

        config = LambdaApiConfig(
            runtime=lambda_.Runtime.PYTHON_3_14,
        )

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

LambdaApi creates the REST API when no API object or api_type is supplied. The config selects the Python 3.14 Lambda runtime used by the generated function.

Lambda handler​

The complete lambdas/hello.py is:

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!"}),
    }

@GET("/hello") records the route declaration that CDK discovers and connects to the generated Lambda integration for GET /hello.

Main files and tests​

quickstart-rest/
├── app.py
├── cdk.json
├── requirements.txt
├── requirements-dev.txt
├── quickstart_rest/
│   └── quickstart_rest_stack.py
├── lambdas/
│   ├── __init__.py
│   ├── hello.py
│   └── requirements.txt
└── tests/
    ├── test_hello.py
    └── test_stack.py

test_hello.py checks the handler response. test_stack.py checks the REST API, GET method, /hello resource, Lambda function, and Python 3.14 runtime.

note

Docker must be running for the infrastructure test and cdk synth, because CDK packages the Python Lambda with PythonFunction.

Run the project​

Run these commands from quickstart-rest.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
pytest -q
cdk synth --quiet
cdk bootstrap
cdk deploy
caution

Run cdk bootstrap and cdk deploy only with the intended AWS account and credentials configured.

Test the API​

After deployment, use the API URL printed by CDK and append /hello:

curl "https://YOUR_REST_API_ID.execute-api.YOUR_REGION.amazonaws.com/prod/hello"

The response is JSON containing Hello, world!.

Clean up​

cdk destroy

Complete source​

See the complete quickstart-rest directory for the runnable project and its README.