Forem: Balaji Sivakumar

🏗️ Part 2 — Running a Serverless API Locally with AWS SAM (API Gateway + Lambda + DynamoDB)

Balaji Sivakumar — Sun, 16 Nov 2025 04:02:52 +0000

📘 Serverless TODO App — Article Series

Part	Title
1	Architecture Overview
2	Local Backend with AWS SAM (You are here)
3	Deploying Backend to AWS (SAM + CDK) - (Coming soon…)

🏗️ Part 2 — Running a Serverless API Locally with AWS SAM

(API Gateway + Lambda + DynamoDB Local)

This article expands on Part 1, diving into how the backend works and how to run it fully locally using:

AWS SAM
Local Lambda (Docker)
DynamoDB Local
Seed scripts
curl-based testing

This ensures rapid, cost-free development before deploying to AWS (in Part 3).

🔗 GitHub Repo:

👉 aws-sam-gateway-lambda-dynamodb

Scope: Part 2 is local-only. Cloud deploy, auth, and hardening land in Part 3.

🧰 Prerequisites for Local-Only

🎯 What This Part Covers

How Lambda routing, validation, and DB access work together
How SAM emulates API Gateway + Lambda
How DynamoDB Local integrates via environment variables
Full local run workflow
curl commands to test every endpoint

🧭 Why Local-First Development?

Local-first gives:

Instant iteration
No AWS costs
Offline development
Safe experimentation
Faster debugging
Confidence before cloud deployment

SAM provides a near-identical Lambda runtime locally using Docker.

🏗️ Architecture Overview & What You’ll Build

Single Lambda handles all /todos routes, talking to DynamoDB Local via SAM’s local API Gateway:

┌──────────────────────────┐
│ API Gateway (Local)      │
└──────────────┬───────────┘
               │
        /todos routes
               │
┌──────────────▼───────────┐
│ AWS Lambda (Python 3.13) │  <-- src/app.py
│ Router + Handlers (Local)│
└──────────────┬───────────┘
               │ boto3
┌──────────────▼───────────┐
│ DynamoDB (Local)         │
└──────────────────────────┘

🧩 What the Backend Does

CRUD API for TODO items:

Method	Route	Description
GET	/todos	List all items
GET	/todos/{id}	Get by ID
POST	/todos	Create
PUT	/todos/{id}	Update
DELETE	/todos/{id}	Delete

🧠 Deep Dive — How the Lambda Works

Below are the essential excerpts needed to understand the backend logic.

1️⃣ Lambda Router (src/app.py)

def handler(event, context):
    path = event.get("resource") or event.get("path", "")
    http_method = event.get("httpMethod", "GET").upper()
    path_params = event.get("pathParameters") or {}

    if path == "/todos" and http_method == "POST":
        return create_todo(event)
    if path == "/todos" and http_method == "GET":
        return list_todos(event)
    if path == "/todos/{id}" and http_method == "GET":
        return get_todo(path_params.get("id"))
    if path == "/todos/{id}" and http_method == "PUT":
        return update_todo(path_params.get("id"), event)
    if path == "/todos/{id}" and http_method == "DELETE":
        return delete_todo(path_params.get("id"))

    return _response(404, {"message": "Not Found"})

✔ Simple but effective routing

✔ One Lambda for all endpoints

✔ Fast & cost-efficient

2️⃣ Pydantic Models (src/models.py)

class TodoCreate(BaseModel):
    title: str = Field(min_length=1)
    description: Optional[str] = None
    status: str = Field(default="pending")  # pending|done

class TodoUpdate(BaseModel):
    title: Optional[str] = None
    description: Optional[str] = None
    status: Optional[str] = None

✔ Ensures clean validation

✔ Protects API from malformed payloads

3️⃣ DynamoDB Layer (src/ddb.py)

ddb = boto3.resource(
    "dynamodb",
    endpoint_url=os.getenv("DDB_ENDPOINT")  # Local or AWS
)

table = ddb.Table(os.getenv("TABLE_NAME"))

This makes the DB layer environment-agnostic.

4️⃣ Example Handler — Create Todo

def create_todo(data):
    payload = TodoCreate(**json.loads(data.get("body") or "{}"))

    item = {
        "id": str(uuid.uuid4()),
        "title": payload.title,
        "description": payload.description,
        "status": payload.status,
        "created_at": TodoItem.now_iso(),
        "updated_at": TodoItem.now_iso(),
    }

    table.put_item(Item=item)

    return _response(201, item)

✔ Validated input

✔ UUID generation

✔ Auto timestamps

5️⃣ SAM Template — What Each Part Does

Globals – shared settings for every Lambda: Python 3.13 runtime, 20s timeout, and env vars (TABLE_NAME, DDB_ENDPOINT) so code can read os.environ instead of hardcoding values.
TodoTable (DynamoDB) – a pay-per-request table named ${StackName}-todos with partition key id and a status-index GSI (Global Secondary Index). This is where all TODO items live.
HttpApi (API Gateway) – creates the /v1 HTTP API with permissive CORS so you can call it from anywhere during dev.
TodoFunction (Lambda)
- CodeUri: src/, Handler: app.handler → entry point is src/app.py::handler.
- Policies: DynamoDBCrudPolicy → grants this Lambda CRUD access to TodoTable.
- Events wire HTTP verbs/paths to the single function:
- POST /todos, GET /todos, GET /todos/{id}, PUT /todos/{id}, DELETE /todos/{id}
- DDB_ENDPOINT is empty in AWS (uses managed DynamoDB). For local runs, set it in env_local.json to hit DynamoDB Local.
- sam local start-api reads these mappings so local routing mirrors production.
Outputs – surface the API URL and table name after deploy so you can copy/paste them into tests or clients.

🏃‍♂️ Running the Backend Locally

1️⃣ Start DynamoDB Local

docker compose up -d

If you don’t have AWS creds configured, export dummy values so CLI + seed script work:

export AWS_ACCESS_KEY_ID=dummy
export AWS_SECRET_ACCESS_KEY=dummy
export AWS_REGION=ca-central-1

2️⃣ Create & Activate Python Virtual Environment using venv

macOS / Linux:

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

Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r src/requirements.txt

Deactivate any time:

deactivate

3️⃣ Seed Data

export TABLE_NAME=local-todos
export DDB_ENDPOINT=http://localhost:8000
python3 scripts/seed_local_ddb.py

4️⃣ Build the Project

sam build

5️⃣ Create env_local.json

{
  "TodoFunction": {
    "TABLE_NAME": "local-todos",
    "DDB_ENDPOINT": "http://host.docker.internal:8000"
  }
}

6️⃣ Start Local API Gateway

sam local start-api --env-vars env_local.json
# Add --debug to see detailed SAM logs while developing:
# sam local start-api --env-vars env_local.json --debug

Endpoint:

http://127.0.0.1:3000

7️⃣ Test Endpoints with curl (smoke test)

# Create
curl -sS -X POST http://127.0.0.1:3000/todos   -H 'Content-Type: application/json'   -d '{"title":"First Todo","description":"hello"}' | jq

# List
curl -sS http://127.0.0.1:3000/todos | jq

# Grab an id from the JSON above
ID="1a31c3fc-45b9-44f7-8152-47d258340d60"

# Get one
curl -sS http://127.0.0.1:3000/todos/$ID | jq

# Update
curl -sS -X PUT http://127.0.0.1:3000/todos/$ID   -H 'Content-Type: application/json'   -d '{"status":"done"}' | jq

# Delete
curl -i -sS -X DELETE http://127.0.0.1:3000/todos/$ID

Cloud next steps (covered in Part 3): sam deploy --guided with a real DynamoDB table (leave DDB_ENDPOINT empty).

8️⃣ Stop Local Services

Stop SAM server: hit Ctrl+C in the terminal running sam local start-api.
Stop DynamoDB Local:

  docker compose down

📚 Additional Resources

GitHub Repository:

👉 aws-sam-gateway-lambda-dynamodb

AWS docs for deeper dives:

⏭️ Coming Up in Part 3

Part 3 covers:

Deploying to AWS with SAM
Deploying to AWS with CDK
S3 packaging
API Gateway
DynamoDB
AWS Free Tier vs Always-Free Notes
Budget Alerts to avoid costs

Stay tuned! 🚀

🚀 Building a Serverless TODO App with AWS + Vercel — My First AWS Project

Balaji Sivakumar — Fri, 10 Oct 2025 03:07:23 +0000

📘 Serverless TODO App — Article Series

Part	Title
1	Architecture Overview (You are here)
2	Local Backend with AWS SAM
3	Deploying Backend to AWS (SAM + CDK) - (Coming soon…)

🧰 How I Built a Serverless TODO App with AWS Lambda, DynamoDB & Vercel

I’ve always wanted to build a real full-stack application that’s completely serverless, scalable, and affordable to host.

This project marks that milestone — a simple but powerful TODO App built with React + Vite on Vercel (frontend) and an AWS backend powered by Cognito, Lambda, and DynamoDB.

🎯 Motivation

Most of my side projects started as experiments — a script here, a local app there. But I wanted to go one step further and deploy a working cloud application that could:

Scale without managing servers
Stay within free-tier limits (important for solo devs!)
Integrate modern authentication (AWS Cognito)
Be fully automated using Infrastructure as Code (AWS CDK)

Instead of learning theory from tutorials, I decided to build something end-to-end — a small, achievable project that would teach me how real serverless systems fit together.

🧩 What I Built

Todo App (Vercel + AWS)

A lightweight yet production-ready serverless TODO manager with:

⚛️ React + Vite SPA hosted on Vercel
🔐 AWS Cognito Hosted UI for user authentication (email/password for now, social login ready for later via identity providers)
🧠 AWS Lambda Function URL exposing CRUD endpoints (Create, Read, Update, Delete)
💾 DynamoDB (on-demand mode) to store tasks per user
🛠 AWS CDK (TypeScript) to automate deployment of all backend infrastructure (Cognito, Lambda, DynamoDB, IAM roles, etc.)
🌐 AWS Amplify JS (Auth module) integrated with the frontend to handle sign-in and token-based API calls

Everything is stateless and serverless, meaning no EC2, no manual scaling, and no backend servers to patch — ever.

🏗 Architecture Overview

Here’s the flow:

The React app is deployed to Vercel.
Users sign in using Cognito Hosted UI.
Upon login, the app stores a JWT token.
Every API call goes through the Lambda Function URL, validated using that token.
The Lambda reads and writes tasks to DynamoDB, partitioned by userId.

🧠 Note: Lambda Function URLs are public by default — the token validation happens inside the Lambda to ensure secure access.

It’s clean, secure, and built on services that can scale infinitely.

⚙️ Tech Stack

Layer	Technology
Frontend	React + Vite + AWS Amplify JS (Auth module)
Hosting	Vercel (free tier)
Auth	AWS Cognito Hosted UI
API	AWS Lambda (Function URL)
Database	DynamoDB (on-demand)
IaC	AWS CDK (TypeScript)

💵 AWS Free Tier — Cost & Scalability

One of my key goals was to stay within AWS’s always-free tier, so I could build, test, and learn without worrying about surprise bills.

Here’s how each service fits into the free tier and what kind of traffic it can handle before costs start:

AWS Service	Free Tier Limit	What It Covers	Practical Impact
AWS Lambda	1M requests/month + 400,000 GB-seconds compute/month	All function invocations	Enough for tens of thousands of TODO operations per month. Perfect for hobby apps or small prototypes.
Amazon DynamoDB (On-Demand)	25 GB free storage	Automatically scales with traffic	No need to pre-provision read/write capacity — great for unpredictable workloads.
Amazon Cognito	50,000 monthly active users (MAUs) free	Authentication and token management	Easily supports most side projects and MVPs without cost.
AWS CDK / CloudFormation	Free	Infrastructure management and provisioning	No runtime cost — only pays for created resources (still free if resources are within free tier).
Vercel Hosting	Free plan for hobby projects	Static site hosting and serverless frontend delivery	Perfect for individual or small-team projects.
AWS Amplify Hosting	1,000 build minutes/month + 5 GB storage (free for first year only)	Static site hosting on AWS	Would have kept everything inside AWS, but the free tier is limited to the first year.
AWS Budget & Cost Monitor	Free	Budget alerts and cost tracking	Always set up a budget alert (e.g., $1 threshold) to monitor expenses and avoid surprises.
AWS API Gateway (optional)	1M REST API calls/month	Only if used instead of Lambda URL	Useful for advanced routing or throttling setups later.

🧠 Tip: All of these services automatically scale down when idle, meaning you only pay when your app is being used — ideal for experimentation and side projects.

💡 Lessons Learned

CDK is game-changing — writing infrastructure in TypeScript feels natural once you get used to it.
Vercel + AWS work beautifully together — frontend on Vercel, backend on AWS, no friction.
JWT validation in Lambda keeps APIs lightweight yet secure.
Keeping things modular (frontend + backend folders) makes local dev and deployment easy.
Always configure budget alerts early — they’re free and prevent billing surprises.

🧭 What’s Next

Add Google & GitHub sign-in via Cognito Identity Providers.
Add real-time updates using AWS AppSync or WebSockets.
Build automated deployments using GitHub Actions (with AWS OIDC roles, no static keys).
Write detailed follow-ups on each part (Cognito setup, CDK deployment, etc.).

❤️ Final Thoughts

This project isn’t just a TODO app — it’s a template for future serverless ideas.

If you’re someone who’s been reading about AWS and Vercel but never connected the dots, this kind of project is the perfect start. It’s small enough to finish, yet rich enough to teach you real-world cloud development.

✨ Coming Soon

In my next post, I’ll share a step-by-step guide to set up this project from scratch —

perfect for beginners who want to clone, deploy, and learn while building along.

Stay tuned! 🚀

Thanks for reading 🙏

This was my first post on Dev.to — more articles coming soon!