DEV Community: Fotseu Josué

Getting Started with AWS CDK: Build a Serverless API with DynamoDB, Lambda, and API Gateway in Python

Fotseu Josué — Wed, 19 Aug 2026 22:49:41 +0000

If you have been building on AWS by clicking through the console (also called ClickOps), AWS CDK is the upgrade you need. Instead of manually creating resources every time, you write code that describes your entire infrastructure, and CDK deploys it for you. Every time. Consistently. Without mistakes.

In this article, I will walk you through building a complete serverless CRUD API on AWS using CDK and Python. By the end, you will have a real API endpoint that can create, read, update, and delete items in a DynamoDB table, all provisioned with just a few Python files and a single deploy command.

What is AWS CDK and Why Should You Care?

Before CDK, Infrastructure as Code (IaC) on AWS was done using CloudFormation, where you had to write long YAML or JSON files to describe every resource. It worked, but it was painful. You had to learn a new syntax and even creating one simple Lambda function required dozens of lines of configuration.

CDK (Cloud Development Kit) solves this. You write infrastructure in a real programming language (Python, TypeScript, Java, Go, etc.), and CDK converts it into CloudFormation under the hood. You get all the power of a programming language (loops, conditions, functions, type checking) applied to your infrastructure.

One concept to understand before we start:

Stack: A stack is a group of related AWS resources that are deployed and managed together. Think of it as one deployment unit. Everything you create in a stack gets deployed at once, and destroyed at once.

Here is the architecture we are going to build:

Lambda -> DynamoDB." width="800" height="388">

Prerequisites

AWS CLI installed and configured (aws configure)
Python 3.8 or higher
Node.js installed (CDK runs on Node.js internally)
AWS CDK installed: npm install -g aws-cdk

Step 1: Initialize the CDK Project

Create a new directory and initialize a CDK project in Python:

mkdir cdkTutorial_crudApi && cd cdkTutorial_crudApi
cdk init app --language python

This generates a project with several files. The important one is the stack file (named something like cdk_tutorial_crud_api/cdk_tutorial_crud_api_stack.py). This is where you will define all your AWS resources.

Also create a lambda/ folder at the root of the project. This is where the Lambda function code will live:

mkdir lambda

Now activate your virtual environment and install the dependencies listed in requirements.txt:

# On Mac/Linux
source .venv/bin/activate

# On Windows
.venv\Scripts\activate

pip install -r requirements.txt

Step 2: Bootstrap Your AWS Account

Before deploying anything with CDK, you need to run this command once per AWS account and region:

cdk bootstrap

What this does: it creates an S3 bucket in your account that CDK uses to store deployment assets (like your zipped Lambda code). When you later run cdk deploy, CDK uploads those assets to that bucket and deploys everything from there.

The great advantage of this: if you push your code to GitHub and come back a year later, running cdk deploy will recreate the exact same infrastructure without any manual steps or changes.

Step 3: Create the DynamoDB Table

The first resource we will create is the DynamoDB table. This is the database that will store all items our API will manage. Open your stack file and add the following code:

from aws_cdk import (
    Stack,
    RemovalPolicy,  # Controls what happens to resources when you delete the stack
    CfnOutput,      # Prints useful values after deployment
    aws_dynamodb as dynamodb,
)
from constructs import Construct  # The base class for all CDK resources


class CdkTutorialCrudApiStack(Stack):

    def __init__(self, scope: Construct, id: str, **kwargs) -> None:
        # Pass any extra settings (like AWS region) to the parent Stack class
        super().__init__(scope, id, **kwargs)

        # --- DATABASE ---
        # Create a DynamoDB table to store our items
        items_table = dynamodb.Table(
            self,           # means: put this construct inside the current stack
            "ItemsTable",   # construct ID within the stack (not the actual table name)
            partition_key=dynamodb.Attribute(
                name="id",
                type=dynamodb.AttributeType.STRING,
            ),
            billing_mode=dynamodb.BillingMode.PAY_PER_REQUEST,
            removal_policy=RemovalPolicy.DESTROY,
        )

        # --- OUTPUTS ---
        # Print the table name in the terminal after deployment to confirm it was created
        CfnOutput(
            self,
            "TableName",
            value=items_table.table_name,
            description="DynamoDB table name",
        )

Key things to understand about this stack

Stack and Construct:
Stack is the base class that groups all your AWS resources together as one deployment unit. Construct is the base class for every individual resource inside a stack. When you see self passed as the first argument to a resource, it means "put this resource inside the current stack."

dynamodb.Table vs dynamodb.TableV2:
CDK gives you two constructs for DynamoDB. dynamodb.Table is the standard one we use here. dynamodb.TableV2 is a newer version with enhanced features like native support for Global Tables (multi-region replication). For new production infrastructure, prefer TableV2. For learning, Table is perfectly fine.

"ItemsTable" is the construct ID, not the table name:
Every resource in CDK needs a unique ID within the stack. "ItemsTable" is that ID. It is not the actual DynamoDB table name in AWS. If you want to give the table a specific name in AWS, you add table_name="your-table-name" as a separate argument. If you do not set it, CloudFormation generates a unique name automatically.

billing_mode=dynamodb.BillingMode.PAY_PER_REQUEST:
This means you only pay when the table is actually read from or written to. There is no capacity to pre-provision. For a tutorial like this, it is the most cost-effective option.

removal_policy=RemovalPolicy.DESTROY:
This controls what happens to the table when you run cdk destroy. DESTROY means the table (and all its data) gets deleted along with the stack. This is the right setting for a learning project. In production, you would use RemovalPolicy.RETAIN to protect your data from accidental deletion.

CfnOutput:
After CDK deploys your stack, CfnOutput prints values in the terminal so you can confirm the resources were created. Here it prints the actual table name that CloudFormation assigned after deployment. items_table.table_name is a CDK reference that resolves to the real name once CloudFormation finishes creating the table.

Deploy the DynamoDB table

Before deploying, always run cdk diff first. This command compares what is currently in your AWS account with what your stack is about to deploy, and shows you exactly what will be added, modified, or removed. It is a safety check before making any real changes to AWS.

cdk diff

Once you are satisfied with what cdk diff shows, deploy:

cdk deploy

After the deployment finishes, check the terminal output. You should see the TableName output printed, confirming the table was created. You can also verify it in the AWS console by going to DynamoDB and looking for the table.

Step 4: Write the Lambda Function

Now we write the Lambda function that will handle all the CRUD operations. Inside the lambda/ folder, create a file called index.py and paste the code below.

This single file handles every HTTP route. API Gateway sends every request to this one function, and the function routes it to the correct operation based on the HTTP method and path.

import json
import os
import uuid
import boto3  # AWS SDK for Python, pre-installed in every Lambda runtime

# Connect to DynamoDB using the table name passed in as an environment variable.
# CDK sets this variable automatically when it creates the Lambda function (you will see how in Step 5).
dynamodb = boto3.resource("dynamodb")
table = dynamodb.Table(os.environ["TABLE_NAME"])


def handler(event, context):
    """
    Main entry point for the Lambda function.
    API Gateway sends an 'event' dict containing the HTTP method, path,
    body, and any path parameters. This function routes to the right
    operation based on the HTTP method and path.
    """
    http_method = event["httpMethod"]   # "GET", "POST", "PUT", or "DELETE"
    path = event.get("resource", "")   # "/items" or "/items/{id}"

    try:
        # Route to the correct handler based on HTTP method and path
        if http_method == "GET" and path == "/items":
            return get_all_items()
        elif http_method == "GET" and path == "/items/{id}":
            item_id = event["pathParameters"]["id"]
            return get_item(item_id)
        elif http_method == "POST" and path == "/items":
            body = json.loads(event["body"])
            return create_item(body)
        elif http_method == "PUT" and path == "/items/{id}":
            item_id = event["pathParameters"]["id"]
            body = json.loads(event["body"])
            return update_item(item_id, body)
        elif http_method == "DELETE" and path == "/items/{id}":
            item_id = event["pathParameters"]["id"]
            return delete_item(item_id)

        # If none of the routes matched, return 400
        return api_response(400, {"error": "Unsupported route"})

    except Exception as e:
        return api_response(500, {"error": str(e)})


def get_all_items():
    """Scan the table and return all items."""
    result = table.scan()
    return api_response(200, result["Items"])


def get_item(item_id):
    """Fetch a single item by its id."""
    result = table.get_item(Key={"id": item_id})
    if "Item" not in result:
        return api_response(404, {"error": f"Item {item_id} not found"})
    return api_response(200, result["Item"])


def create_item(body):
    """Create a new item with a generated UUID."""
    item = {
        "id": str(uuid.uuid4()),  # Generate a unique id automatically
        "name": body.get("name", ""),
        "description": body.get("description", ""),
    }
    table.put_item(Item=item)
    return api_response(201, item)


def update_item(item_id, body):
    """Update an existing item's name and description."""
    result = table.update_item(
        Key={"id": item_id},
        # UpdateExpression is DynamoDB's syntax for partial updates.
        # SET means "change these fields". :n and :d are placeholders
        # that map to the values in ExpressionAttributeValues below.
        UpdateExpression="SET #n = :n, description = :d",
        # "name" is a reserved word in DynamoDB, so we use #n as an alias
        ExpressionAttributeNames={"#n": "name"},
        ExpressionAttributeValues={
            ":n": body.get("name", ""),
            ":d": body.get("description", ""),
        },
        ReturnValues="ALL_NEW",  # Return the full item after the update
    )
    return api_response(200, result["Attributes"])


def delete_item(item_id):
    """Delete an item by its id."""
    table.delete_item(Key={"id": item_id})
    return api_response(200, {"message": f"Deleted {item_id}"})


def api_response(status_code, body):
    """
    Build the response dict that API Gateway expects.
    API Gateway requires this exact format: statusCode, headers, and body.
    The body must be a JSON string, not a Python dict.
    """
    return {
        "statusCode": status_code,
        "headers": {
            "Content-Type": "application/json",
            # Allow requests from any origin (fine for a tutorial,
            # restrict this to your frontend domain in production)
            "Access-Control-Allow-Origin": "*",
        },
        "body": json.dumps(body, default=str),  # default=str handles DynamoDB Decimal types
    }

Step 5: Add the Lambda Function to the Stack

Now go back to the stack file and add the Lambda construct. You are not replacing the DynamoDB code from Step 3, you are adding the Lambda construct below it. Replace the full content of your stack file with the code below:

from aws_cdk import (
    Stack,
    RemovalPolicy,  # Controls what happens to resources when you delete the stack
    CfnOutput,      # Prints useful values after deployment
    Duration,       # Used to set the Lambda timeout
    aws_dynamodb as dynamodb,
    aws_lambda as _lambda,
)
from constructs import Construct


class CdkTutorialCrudApiStack(Stack):

    def __init__(self, scope: Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # --- DATABASE ---
        items_table = dynamodb.Table(
            self,
            "ItemsTable",
            partition_key=dynamodb.Attribute(
                name="id",
                type=dynamodb.AttributeType.STRING,
            ),
            billing_mode=dynamodb.BillingMode.PAY_PER_REQUEST,
            removal_policy=RemovalPolicy.DESTROY,
        )

        # --- LAMBDA FUNCTION ---
        api_handler = _lambda.Function(
            self,
            "MyFunction",
            runtime=_lambda.Runtime.PYTHON_3_13,     # Python version to use
            handler="index.handler",                  # Run the handler() function in index.py
            code=_lambda.Code.from_asset("lambda"),   # Zip and upload the lambda/ folder
            architecture=_lambda.Architecture.ARM_64, # Graviton: cheaper and faster than x86
            environment={
                # Pass the table name to the Lambda as an environment variable.
                # This is how index.py knows which table to connect to.
                "TABLE_NAME": items_table.table_name,
            },
            timeout=Duration.seconds(10),  # Default is 3s, which is too short for DynamoDB calls
            memory_size=128,
        )

        # --- PERMISSIONS ---
        # Grant the Lambda function permission to read and write to the DynamoDB table.
        # Without this line, every API call returns AccessDeniedException.
        items_table.grant_read_write_data(api_handler)

        # --- OUTPUTS ---
        CfnOutput(
            self,
            "TableName",
            value=items_table.table_name,
            description="DynamoDB table name",
        )

Key things to understand about the Lambda construct

handler="index.handler":
This tells Lambda which function to run when it is invoked. The format is filename.function_name. So "index.handler" means: find index.py in the uploaded code, then call the handler() function inside it. If your file is named differently or your function has a different name, this line must match.

code=_lambda.Code.from_asset("lambda"):
CDK zips the entire lambda/ folder and uploads it to the S3 bootstrap bucket. When you deploy, Lambda pulls from that bucket. This is why the cdk bootstrap step was necessary.

architecture=_lambda.Architecture.ARM_64:
This runs the Lambda on AWS Graviton (ARM) processors instead of x86. Graviton is generally cheaper and faster for most workloads. Unless you have a specific reason to use x86, ARM_64 is the better default.

environment={"TABLE_NAME": items_table.table_name}:
This is how the Lambda function knows which DynamoDB table to connect to. Instead of hardcoding the table name inside index.py, we pass it as an environment variable from the stack. This is the right approach because the actual table name is generated by CloudFormation at deploy time and is not known until then. In index.py, the function reads this with os.environ["TABLE_NAME"].

timeout=Duration.seconds(10):
Lambda's default timeout is 3 seconds. DynamoDB calls can sometimes take longer than that, especially on cold starts. Setting it to 10 seconds gives the function enough room to complete without timing out unexpectedly.

items_table.grant_read_write_data(api_handler):
This is one of the most important lines in the entire stack. CDK automatically generates the correct IAM policy and attaches it to the Lambda's execution role, giving it permission to perform GetItem, PutItem, UpdateItem, DeleteItem, and Scan on the table. Without this, every single API call will fail with AccessDeniedException.

Deploy the stack with Lambda

Run cdk diff to preview what is about to change. Since you already deployed the DynamoDB table, this will show only the new Lambda-related resources being added:

cdk diff

Then deploy:

cdk deploy

After deployment:

After deployment, verify the Lambda function exists:

aws lambda list-functions --query "Functions[?starts_with(FunctionName, 'CrudApiStack')].FunctionName" --output text

Step 6: Add the API Gateway

Now we add the final piece: the API Gateway that exposes our Lambda function as HTTP endpoints. Replace the full content of your stack file with this final version:

from aws_cdk import (
    Stack,
    RemovalPolicy,
    CfnOutput,
    Duration,
    aws_dynamodb as dynamodb,
    aws_lambda as _lambda,
    aws_apigateway as apigw,
)
from constructs import Construct


class CdkTutorialCrudApiStack(Stack):

    def __init__(self, scope: Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # --- DATABASE ---
        items_table = dynamodb.Table(
            self,
            "ItemsTable",
            partition_key=dynamodb.Attribute(
                name="id",
                type=dynamodb.AttributeType.STRING,
            ),
            billing_mode=dynamodb.BillingMode.PAY_PER_REQUEST,
            removal_policy=RemovalPolicy.DESTROY,
        )

        # --- LAMBDA FUNCTION ---
        api_handler = _lambda.Function(
            self,
            "MyFunction",
            runtime=_lambda.Runtime.PYTHON_3_13,
            handler="index.handler",
            code=_lambda.Code.from_asset("lambda"),
            architecture=_lambda.Architecture.ARM_64,
            environment={
                "TABLE_NAME": items_table.table_name,
            },
            timeout=Duration.seconds(10),
            memory_size=128,
        )

        # --- API GATEWAY ---
        api_endpoints = apigw.LambdaRestApi(
            self,
            "itemsApi",
            handler=api_handler,        # Which Lambda to send requests to
            proxy=False,                # We define routes manually (no catch-all)
            rest_api_name="Items Service",
            description="CRUD API for items, built with CDK",
            default_cors_preflight_options=apigw.CorsOptions(
                allow_origins=apigw.Cors.ALL_ORIGINS,
                allow_methods=apigw.Cors.ALL_METHODS,
                allow_headers=apigw.Cors.DEFAULT_HEADERS,
            ),
        )

        # Define the routes (resources and methods)
        # /items
        items = api_endpoints.root.add_resource("items")
        items.add_method("GET")    # GET /items  -> get all items
        items.add_method("POST")   # POST /items -> create an item

        # /items/{id}
        item = items.add_resource("{id}")
        item.add_method("GET")     # GET /items/{id}    -> get one item
        item.add_method("PUT")     # PUT /items/{id}    -> update an item
        item.add_method("DELETE")  # DELETE /items/{id} -> delete an item

        # --- PERMISSIONS ---
        items_table.grant_read_write_data(api_handler)

        # --- OUTPUTS ---
        CfnOutput(
            self,
            "TableName",
            value=items_table.table_name,
            description="DynamoDB table name",
        )
        CfnOutput(
            self,
            "ApiUrl",
            value=api_endpoints.url,
            description="API Gateway endpoint URL",
        )

Key things to understand about the API Gateway

apigw.LambdaRestApi vs apigw.RestApi:
LambdaRestApi is a higher-level construct that automatically connects API Gateway to a Lambda function. You just specify handler=api_handler and CDK handles all the integration wiring behind the scenes (permissions, Lambda invocation setup). RestApi is the lower-level version that gives you more granular control, for example when different routes need to go to different Lambda functions. For this project where one Lambda handles everything, LambdaRestApi is the right choice.

proxy=False:
By default, LambdaRestApi creates a greedy catch-all route (ANY /{proxy+}) that forwards all incoming requests to Lambda without you defining any routes. Setting proxy=False disables that and allows you to explicitly define each route and method yourself using add_resource() and add_method(). This is the better approach when you want control over exactly which HTTP methods are allowed on each path.

Important: this proxy setting is different from Lambda Proxy Integration. LambdaRestApi always uses Lambda Proxy Integration regardless of whether proxy is True or False. Lambda Proxy Integration means API Gateway forwards the full HTTP request (method, headers, body, path parameters) to Lambda as a JSON event object, and Lambda returns the full response including statusCode, headers, and body. That is why index.py reads event["httpMethod"] and returns {"statusCode": 200, ...}.

add_resource() and add_method():
These two methods define the API structure. add_resource("items") creates the /items path. add_resource("{id}") on top of that creates /items/{id} where {id} is a dynamic path parameter captured and passed to Lambda as event["pathParameters"]["id"]. add_method("GET") attaches an HTTP method to a resource.

CORS configuration:
The default_cors_preflight_options block is what handles Cross-Origin Resource Sharing. Before a browser sends a POST, PUT, or DELETE request to an API on a different domain, it first sends an OPTIONS preflight request to check if the API allows it. This block tells CDK to create an OPTIONS method on every route automatically. For a tutorial, allow_origins=apigw.Cors.ALL_ORIGINS is fine. For production, restrict it to your actual frontend domain like this:

default_cors_preflight_options=apigw.CorsOptions(
    allow_origins=["https://my-frontend.example.com", "http://localhost:3000"],
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["Content-Type", "Authorization"],
)

The Lambda function also returns "Access-Control-Allow-Origin": "*" in every response through api_response(). These two CORS settings work together: the CDK config handles the browser's early OPTIONS preflight request, and the Lambda header handles the CORS policy on the actual API response.

CfnOutput for the API URL:
After deployment, api_endpoints.url resolves to the live API Gateway base URL. CDK prints it in the terminal via CfnOutput so you can copy it directly and start testing.

Deploy the stack with API Gateway

Run cdk diff to see the new API Gateway resources that will be added:

cdk diff

Then deploy:

cdk deploy

After deployment, the terminal will print both outputs:

Outputs:
CdkTutorialCrudApiStack.ApiUrl = https://xxxxxxxxxx.execute-api.us-east-1.amazonaws.com/prod/
CdkTutorialCrudApiStack.TableName = CdkTutorialCrudApiStack-ItemsTable...

Copy the ApiUrl. You will need it in the next step.

Step 7: Test the API

Use curl to test every endpoint. Replace YOUR_API_URL with the URL from your deployment output.

Create an item (POST):

# Git Bash / Mac / Linux
curl -X POST https://YOUR_API_URL/prod/items \
  -H "Content-Type: application/json" \
  -d '{"name": "Chocolate", "description": "The fancy barista edition"}'

# PowerShell
$API_URL = "https://YOUR_API_URL/prod"
Invoke-RestMethod -Uri "$API_URL/items" -Method POST -ContentType 'application/json' -Body '{"name":"Chocolate","description":"The fancy barista edition"}'

The response will include an id. Copy it and use it in the commands below.

Get all items (GET):

curl https://YOUR_API_URL/prod/items

Get a single item (GET):

curl https://YOUR_API_URL/prod/items/PASTE-YOUR-ID-HERE

Update an item (PUT):

curl -X PUT https://YOUR_API_URL/prod/items/PASTE-YOUR-ID-HERE \
  -H "Content-Type: application/json" \
  -d '{"name": "Dark Chocolate", "description": "Even fancier edition"}'

Delete an item (DELETE):

curl -X DELETE https://YOUR_API_URL/prod/items/PASTE-YOUR-ID-HERE

Step 8: See the CloudFormation Output

Want to see what CDK generates under the hood? Run:

cdk synth

This prints the CloudFormation YAML that CDK produces from your Python code. It is a great way to understand what is actually being sent to AWS, and to appreciate why writing CDK is so much cleaner than writing CloudFormation by hand. One Lambda function in CDK is about 10 lines. The CloudFormation equivalent can be over 100 lines of YAML.

Step 9: Clean Up

When you are done, delete all the resources you created:

cdk destroy

This removes everything from your AWS account in one command. And because all the infrastructure lives in your code, you can bring it all back anytime by running cdk deploy again.

Common Errors and How to Fix Them

"This stack uses assets, so the toolkit stack must be deployed"

You forgot to bootstrap. Run this once per account and region:

cdk bootstrap

"User: arn:aws:iam::... is not authorized"

Your AWS CLI user does not have enough permissions to deploy CDK resources. For a personal learning account, attach AdministratorAccess to your IAM user. Never do this in a shared or production account, scope permissions to only what CDK requires.

"Runtime.ImportModuleError: Unable to import module 'index'"

CDK cannot find your Lambda file. The error means Lambda loaded successfully but could not find index.py to import. Make sure:

The lambda/ folder exists at the root of your project
The file inside it is named exactly index.py
The handler="index.handler" line in your stack matches that filename

Verify with:

ls lambda/

"AccessDeniedException: ... is not authorized to perform: dynamodb:PutItem"

Your Lambda function does not have permission to write to DynamoDB. This means the permissions line is either missing or placed before the table is defined. Make sure this line exists in your stack, after the items_table and api_handler are both defined:

items_table.grant_read_write_data(api_handler)

Wrapping Up

In this article you built a complete serverless CRUD API on AWS using Infrastructure as Code, without clicking through the console once. Here is a summary of every command and what it does:

Command / Code	What it does
`cdk bootstrap`	Sets up the S3 bucket CDK needs to deploy assets
`cdk diff`	Previews changes before they are applied to AWS
`cdk deploy`	Deploys the stack and provisions all resources
`cdk synth`	Shows the CloudFormation YAML CDK generates
`cdk destroy`	Removes all stack resources from AWS
`dynamodb.Table(...)`	Creates the DynamoDB database
`_lambda.Function(...)`	Creates the Lambda compute layer
`apigw.LambdaRestApi(...)`	Creates the HTTP API endpoints
`grant_read_write_data(...)`	Gives Lambda IAM permission to access DynamoDB

The biggest advantage of CDK over ClickOps is repeatability. Your infrastructure is versioned, reviewable, and reproducible. Push it to GitHub and anyone on your team (or future you) can deploy the exact same setup with one command.

You can find the full source code here: github.com/Joshua4-0p/Simple-CRUD-API-Using-IaC-and-aws-CDK

Have questions or ran into a different error? Drop it in the comments.

Building a Serverless CRUD API on AWS with JavaScript (Lambda + DynamoDB + API Gateway)

Fotseu Josué — Thu, 13 Aug 2026 18:00:58 +0000

If you have ever wanted to build a backend without managing a single server, AWS gives you everything you need. In this article, I walk through how I built a fully functional serverless CRUD API using AWS Lambda, DynamoDB, and API Gateway, all written in JavaScript using the AWS SDK v3. I also cover how to secure those endpoints and make the whole system scalable using SQS.

Here is what we will build:

A DynamoDB table as the database
Lambda functions for each CRUD operation
An API Gateway to expose those functions as HTTP endpoints
Endpoint security using API keys and usage plans
A scalable upload pipeline using SQS (Producer/Consumer pattern)

The AWS Services at a Glance

Before jumping into code, here is a quick mental model of the services involved:

Service	Role
DynamoDB	NoSQL database where data is stored
Lambda	Serverless functions that run your business logic
API Gateway	HTTP layer that routes requests to Lambda
SQS	Queue that decouples and scales heavy workloads
Amplify	Hosts the frontend and connects to the backend

1. Setting Up DynamoDB

Start by creating a DynamoDB table from the AWS Console. For this project, the table is named aws_introduction-table with id as the partition key (String type).

You can also seed data manually from the console using the DynamoDB JSON format:

{
  "id": { "S": "cat-001" },
  "name": { "S": "Cloud Whisker" },
  "image_url": { "S": "https://example.com/cat.jpg" }
}

Key data type formats in DynamoDB JSON:

String: { "S": "value" }
Number: { "N": "123" }
Boolean: { "BOOL": true }
List: { "L": [...] }
Map: { "M": {...} }

2. Writing the Lambda Functions (AWS SDK v3)

Important note on imports: The old require("aws-sdk") is no longer valid in modern Node.js Lambda runtimes. You must now import only the specific client and command you need.

GET All Items

import { DynamoDBClient, ScanCommand } from "@aws-sdk/client-dynamodb";
import { unmarshall } from "@aws-sdk/util-dynamodb";

// Initialize the client once, outside the handler (reused across warm invocations)
const client = new DynamoDBClient({});

export const handler = async (event) => {
  const params = {
    TableName: "aws_introduction-table",
  };

  try {
    // ScanCommand acts as an envelope: packages your request into a format DynamoDB understands
    const command = new ScanCommand(params);
    // client.send() carries the command to DynamoDB, gets the response, and returns it
    const data = await client.send(command);

    // unmarshall converts DynamoDB's typed format ({ S: "value" }) into plain JS objects
    const cleanItems = data.Items.map((item) => unmarshall(item));

    return {
      statusCode: 200,
      body: JSON.stringify({
        message: "Successfully retrieved all items",
        items: cleanItems,
      }),
    };
  } catch (err) {
    console.error("Error reading from DynamoDB:", err);
    return {
      statusCode: 500,
      body: JSON.stringify({ error: err.message }),
    };
  }
};

GET a Single Item

For a single item lookup, the function reads an id from the request headers. This requires Lambda Proxy Integration to be enabled on the API Gateway route, otherwise the headers are stripped and the function receives an empty event.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, GetCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({ region: "us-east-1" });
const docClient = DynamoDBDocumentClient.from(client);

export const handler = async (event) => {
  // Support both API Gateway (headers) and direct Lambda invocation (event.id)
  const incomingId = event.headers?.["id"] || event.headers?.["Id"];
  const finalId = incomingId || event.id;

  const params = {
    TableName: "aws_introduction-table",
    Key: { id: finalId },
  };

  try {
    const command = new GetCommand(params);
    const response = await docClient.send(command);

    return {
      statusCode: 200,
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        message: "Item retrieved successfully",
        // GetCommand returns response.Item (singular), not response.Items
        data: response.Item,
      }),
    };
  } catch (err) {
    console.error("Error reading from DynamoDB:", err);
    return {
      statusCode: 500,
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ error: err.message }),
    };
  }
};

POST (Add an Item)

There are two ways to write items to DynamoDB. Pick one approach and stick with it per function.

Option A: Using JavaScript objects (recommended for readability)

Uses DynamoDBDocumentClient from @aws-sdk/lib-dynamodb, which lets you write plain JS objects instead of typed DynamoDB JSON.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";

const baseClient = new DynamoDBClient({});
// DynamoDBDocumentClient wraps the base client so you skip the { S: "..." } typing
const docClient = DynamoDBDocumentClient.from(baseClient);

export const handler = async (event) => {
  const { userId, userName, email } = event;

  const params = {
    TableName: "aws_introduction-table",
    Item: {
      id: userId,
      name: userName,
      email: email,
      createdAt: new Date().toISOString(),
    },
  };

  try {
    const command = new PutCommand(params);
    await docClient.send(command);

    return {
      statusCode: 201,
      body: JSON.stringify({
        message: "Item added successfully!",
        savedItem: params.Item,
      }),
    };
  } catch (err) {
    console.error("Error adding item:", err);
    return {
      statusCode: 500,
      body: JSON.stringify({ error: err.message }),
    };
  }
};

Option B: Using raw DynamoDB JSON format

If you prefer (or need) to use the raw typed format, use PutItemCommand from @aws-sdk/client-dynamodb instead. Mixing PutCommand (lib-dynamodb) with raw DynamoDB types will cause a type mismatch error.

import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({});

export const handler = async (event) => {
  const { id, name, image_url } = event;

  const params = {
    TableName: "aws_introduction-table",
    Item: {
      id: { S: id },
      name: { S: name },
      image_url: { S: image_url },
    },
  };

  try {
    const command = new PutItemCommand(params);
    await client.send(command);

    return {
      statusCode: 201,
      body: JSON.stringify({
        message: "Item added successfully",
        savedItems: params.Item,
      }),
    };
  } catch (err) {
    console.error("Error writing to DynamoDB:", err);
    return {
      statusCode: 500,
      body: JSON.stringify({ error: err.message }),
    };
  }
};

PATCH (Update an Item)

The UpdateExpression syntax is what makes DynamoDB updates flexible. :var is a placeholder that gets replaced by ExpressionAttributeValues.

Using JavaScript objects format:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, UpdateCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);

export const handler = async (event) => {
  const params = {
    TableName: "aws_introduction-table",
    Key: {
      id: event.id,
    },
    UpdateExpression: "SET image_url = :var", // :var is a placeholder
    ExpressionAttributeValues: {
      ":var": event.image_url, // replaces the placeholder with the incoming value
    },
    ReturnValues: "ALL_NEW", // returns the entire updated record
  };

  try {
    const command = new UpdateCommand(params);
    const response = await docClient.send(command);

    return {
      statusCode: 200,
      body: JSON.stringify("Record successfully updated"),
      data: response,
    };
  } catch (err) {
    console.error("Error updating the record:", err);
    return {
      statusCode: 500,
      body: JSON.stringify({ error: err.message }),
    };
  }
};

Using DynamoDB JSON format:

When using the raw format with UpdateItemCommand, you also need ExpressionAttributeNames to avoid conflicts with DynamoDB reserved keywords.

import { DynamoDBClient, UpdateItemCommand } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({});

export const handler = async (event) => {
  const params = {
    TableName: "aws_introduction-table",
    Key: {
      id: { S: event.id }, // DynamoDB JSON format requires type tags on the Key too
    },
    UpdateExpression: "SET #image_url = :var",
    ExpressionAttributeNames: {
      "#image_url": "image_url", // avoids conflicts with reserved keywords
    },
    ExpressionAttributeValues: {
      ":var": { S: event.image_url }, // typed value for DynamoDB JSON format
    },
    ReturnValues: "ALL_NEW",
  };

  try {
    const command = new UpdateItemCommand(params);
    const response = await client.send(command);

    return {
      statusCode: 200,
      body: JSON.stringify("Record successfully updated"),
      data: response,
    };
  } catch (err) {
    console.error("Error updating the record:", err);
    return {
      statusCode: 500,
      body: JSON.stringify({ error: err.message }),
    };
  }
};

DELETE an Item

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, DeleteCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);

export const handler = async (event) => {
  const params = {
    TableName: "aws_introduction-table",
    Key: {
      id: event.id,
    },
  };

  try {
    const command = new DeleteCommand(params);
    const response = await docClient.send(command);

    return {
      statusCode: 200,
      body: JSON.stringify({
        message: "Successfully deleted item",
        data: response,
      }),
    };
  } catch (err) {
    console.error("Delete failed:", err);
    return {
      statusCode: 500,
      body: JSON.stringify({
        message: "Failed to delete item",
        error: err.message,
      }),
    };
  }
};

3. Creating the API Gateway

Once all five Lambda functions are deployed, head to API Gateway and create a REST API. For each function, create a resource and attach the appropriate HTTP method (GET, POST, PATCH, DELETE).

After creating each method, use the built-in Test tab to validate it before moving on.

One critical setting for the GET single item endpoint: Make sure to enable Lambda Proxy Integration. Without it, API Gateway acts as an aggressive filter and drops all headers before forwarding the request to Lambda. Since the single item lookup reads the item id from the request header, disabling proxy integration means the event.headers object will always be empty.

4. Securing the Endpoints

Leaving your API Gateway endpoints open to the internet is a bad idea. Here is how to lock them down using three features that work together.

Stages act as environment snapshots of your deployed API. A /dev stage is isolated from a /prod stage, so you can test changes without breaking production.

Usage Plans attach rate limits and quotas to a stage. You define how many requests per second (throttling) and how many total per day or month (quota) a consumer can make. This protects your Lambda concurrency and prevents your DynamoDB from getting hammered.

API Keys are alphanumeric identifiers tied to a usage plan. Every request must include the key, which lets you track usage per client, revoke access, or offer tiered access in the future.

Note: API keys identify clients but they are not a replacement for authentication. For user-level security, combine them with JWT or AWS Cognito.

Testing secured endpoints in Postman:

For GET and DELETE: include the API key under the Authorization tab
For POST and PATCH: add it as a header with key x-api-key and your API key as the value

5. Making the API Scalable with SQS

AWS Lambda handles up to 1,000 concurrent executions per region by default. For a sudden surge (like 500,000 image uploads in a short window), that ceiling breaks fast.

The solution is to decouple the request intake from the processing using Amazon SQS with a Producer/Consumer Lambda pattern.

Here is how it works:

The Producer Lambda receives requests from API Gateway and pushes them as messages to an SQS queue. It responds immediately to the client.
The SQS queue buffers all the messages.
The Consumer Lambda is triggered automatically by an Event Source Mapping (AWS polls the queue for you) and processes messages in batches.
When Consumer Lambda hits its concurrency limit, SQS automatically provisions additional Lambda instances to keep draining the queue.

Producer Lambda -> SQS Queue -> Consumer Lambda (with multiple instances) -> DynamoDB." width="800" height="356">

Producer Lambda

import { SendMessageCommand, SQSClient } from "@aws-sdk/client-sqs";

// Declare the client globally so it is reused across warm Lambda invocations
const client = new SQSClient({});

const SQS_QUEUE_URL =
  "https://sqs.us-east-1.amazonaws.com/YOUR_ACCOUNT_ID/your-queue-name";

export const handler = async (event) => {
  const params = {
    QueueUrl: SQS_QUEUE_URL,
    MessageBody: JSON.stringify({
      timestamp: new Date().toISOString(),
      data: event,
    }),
  };

  try {
    const command = new SendMessageCommand(params);
    const response = await client.send(command);
    console.log(`Message sent. ID: ${response.MessageId}`);

    return {
      statusCode: 200,
      body: JSON.stringify({
        message: "Event queued successfully!",
        messageId: response.MessageId,
      }),
    };
  } catch (error) {
    return {
      statusCode: 500,
      body: JSON.stringify({
        message: "Error sending message to SQS",
        error: error.message,
      }),
    };
  }
};

Before testing: Go to IAM, find the Producer Lambda's execution role, and grant it sqs:SendMessage permission on your queue.

Consumer Lambda

The Consumer Lambda must not return an HTTP response like { statusCode: 200 }. It is triggered directly by SQS, not by API Gateway, so AWS ignores the return value. More importantly, if you put a return inside your for loop, it exits after the first message and leaves the rest of the batch unprocessed.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);

export const handler = async (event) => {
  // By the time this handler runs, AWS has already polled the queue for you.
  // The messages are handed to you inside event.Records.
  try {
    const writeResults = [];

    for (const record of event.Records) {
      // Step 1: Parse the SQS message body
      const messageBody = JSON.parse(record.body);

      // Step 2: The producer wrapped the API Gateway event inside messageBody.data
      // API Gateway puts the POST body inside data.body as a string, so parse it again
      const apiGatewayBodyString = messageBody.data.body;
      const eventInfo = JSON.parse(apiGatewayBodyString);

      console.log("Processing message:", messageBody);
      console.log("Event info:", eventInfo);

      // Step 3: Write to DynamoDB
      const params = {
        TableName: "your-event-image-table",
        Item: eventInfo,
      };

      const command = new PutCommand(params);
      const response = await docClient.send(command);
      writeResults.push(response);
    }

    // SQS consumers return a generic status, not an HTTP response
    return {
      message: "Batch processed successfully",
      processedCount: event.Records.length,
    };
  } catch (error) {
    console.error("Batch processing failed:", error);
    // Throwing causes SQS to retry the batch. If a message fails 3 times,
    // it is sent to a Dead Letter Queue (DLQ) for inspection.
    throw error;
  }
};

After deploying the Consumer Lambda:

Add an Event Source Mapping by going to the Lambda trigger settings and selecting your SQS queue. This is what tells AWS to continuously poll the queue and invoke your handler automatically.
Go to IAM and grant the Consumer Lambda's role: sqs:ReceiveMessage, sqs:DeleteMessage, sqs:GetQueueAttributes, and full DynamoDB access.

6. Hosting the Frontend on AWS Amplify

Once the backend is solid, the frontend (React + TypeScript + Vite in my case) gets deployed on AWS Amplify, which connects to a GitHub repo and handles builds and deployments automatically.

Here is a quick breakdown of what Amplify uses under the hood:

S3 stores all the static assets (HTML, CSS, JS, images)
CloudFront serves those assets via AWS's CDN, keeping latency low no matter where the user is
WAF (Web Application Firewall) filters out malicious traffic like SQL injection and bot requests before they reach your app
Route 53 lets you connect a custom domain to the Amplify-generated URL

One gotcha with S3 permissions: When writing IAM policies for Lambda to upload files to S3, always append /* to the bucket ARN in the resource field:

arn:aws:s3:::my-bucket/*   ✅ Correct — targets objects inside the bucket
arn:aws:s3:::my-bucket     ❌ Wrong — targets the bucket container itself

s3:PutObject is an object-level action. Without /*, Lambda will get an Access Denied error even with the policy attached.

Another gotcha with CORS: When Lambda Proxy Integration is enabled on API Gateway, API Gateway does not add CORS headers for you. Your Lambda function must return them explicitly in every response:

return {
  statusCode: 200,
  headers: {
    "Content-Type": "application/json",
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Methods": "GET, POST, PATCH, DELETE, OPTIONS",
    "Access-Control-Allow-Headers": "Content-Type, x-api-key",
  },
  body: JSON.stringify({ message: "Success" }),
};

Wrapping Up

This stack (Lambda + DynamoDB + API Gateway + SQS + Amplify) gives you a backend that is fully serverless, scales automatically, and costs almost nothing at low traffic since you only pay per invocation.

The biggest things I learned building this:

The @aws-sdk/v3 import style is stricter but cleaner. Import only what you use.
The choice between DynamoDBDocumentClient (JS objects) and raw DynamoDBClient (DynamoDB JSON) affects which commands you use throughout. Don't mix them.
Lambda Proxy Integration on API Gateway is not optional when your function reads headers or query params.
SQS consumers should never have return inside the processing loop, and they should always throw on failure so SQS retries the batch.
CORS headers must live in your Lambda response when proxy integration is on, not in the API Gateway settings.

If you are just getting started with AWS, this is a solid first project. You touch IAM, compute, storage, queuing, and hosting all in one build.

Have questions or want to see the frontend code too? Drop a comment below.

Insightful post by @tendong_brain! Learned a lot about deploying ML projects on AWS using ECR, ECS Fargate, and EFS. Great practical breakdown for cloud engineers! ☁️

Fotseu Josué — Sat, 09 May 2026 15:53:23 +0000

Tendong Brain Nkengafac

May 9

How to Deploy a Machine Learning Project on AWS Using ECR, ECS Fargate, and EFS.

#ai #python #machinelearning #aws

12 min read

Exploring AI on AWS Made Simpler 🚀

Fotseu Josué — Sat, 09 May 2026 13:52:47 +0000

Tidding Ramsey

May 9

How I Evaluated an AI Model on AWS Without Writing a Single Line of Training Code

#ai #aws #machinelearning #cloudcomputing

6 min read