Project 1: Serverless REST API with API Gateway, Lambda, DynamoDB and Cognito, Deployed by a CI/CD Pipeline
Goal
Build a notes API where signed-in users create, list, update and delete their own notes. It must be secure, tested, observable and deployed automatically.
text
Client โโบ API Gateway HTTP API โ(JWT authorizer: Cognito)โโบ Lambda (Python) โโบ DynamoDB (PK userId, SK noteId)
โ
X-Ray tracing ยท CloudWatch logs + alarms ยท SSM parameters ยท KMS-encrypted table
Git push โโบ CodePipeline โโบ CodeBuild (lint, unit tests, sam build) โโบ deploy test stack โโบ integration tests โโบ manual approval โโบ deploy prod (canary)
Requirements
| # | Requirement |
|---|---|
| 1 | POST /notes, GET /notes, GET /notes/{id}, PUT /notes/{id}, DELETE /notes/{id} |
| 2 | Only the owner can read or change a note (user id from the verified token) |
| 3 | Input validation, JSON errors, idempotent create using an Idempotency-Key header |
| 4 | Pagination for the list endpoint |
| 5 | Unit tests with moto, integration test against a real stack |
| 6 | Canary deployment with automatic rollback on errors |
| 7 | Logs, traces and alarms |
Project Layout
text
otes-api/
โโโ template.yaml
โโโ samconfig.toml
โโโ src/
โ โโโ app.py # handlers
โ โโโ store.py # DynamoDB access
โ โโโ requirements.txt
โโโ tests/
โ โโโ unit/test_app.py
โ โโโ integration/test_api.py
โโโ buildspec.yml
โโโ pipeline.yaml
Step 1: SAM Template
yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Parameters:
Stage: {Type: String, Default: dev, AllowedValues: [dev, test, prod]}
Globals:
Function:
Runtime: python3.12
Architectures: [arm64]
Timeout: 8
MemorySize: 256
Tracing: Active
Environment: {Variables: {TABLE: !Ref NotesTable, LOG_LEVEL: INFO}}
Conditions:
IsProd: !Equals [!Ref Stage, prod]
Resources:
NotesTable:
Type: AWS::DynamoDB::Table
DeletionPolicy: Retain
UpdateReplacePolicy: Retain
Properties:
BillingMode: PAY_PER_REQUEST
AttributeDefinitions: [{AttributeName: userId, AttributeType: S}, {AttributeName: noteId, AttributeType: S}]
KeySchema: [{AttributeName: userId, KeyType: HASH}, {AttributeName: noteId, KeyType: RANGE}]
SSESpecification: {SSEEnabled: true}
PointInTimeRecoverySpecification: {PointInTimeRecoveryEnabled: true}
TimeToLiveSpecification: {AttributeName: expiresAt, Enabled: true} # used by idempotency records
UserPool:
Type: AWS::Cognito::UserPool
Properties:
UsernameAttributes: [email]
AutoVerifiedAttributes: [email]
Policies: {PasswordPolicy: {MinimumLength: 10}}
UserPoolClient:
Type: AWS::Cognito::UserPoolClient
Properties:
UserPoolId: !Ref UserPool
GenerateSecret: false
ExplicitAuthFlows: [ALLOW_USER_SRP_AUTH, ALLOW_USER_PASSWORD_AUTH, ALLOW_REFRESH_TOKEN_AUTH]
Api:
Type: AWS::Serverless::HttpApi
Properties:
StageName: !Ref Stage
Auth:
DefaultAuthorizer: Jwt
Authorizers:
Jwt:
IdentitySource: $request.header.Authorization
JwtConfiguration:
issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool}
audience: [!Ref UserPoolClient]
DefaultRouteSettings: {ThrottlingBurstLimit: 50, ThrottlingRateLimit: 25}
NotesFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: src/
Handler: app.handler
AutoPublishAlias: live
DeploymentPreference:
Type: !If [IsProd, Canary10Percent5Minutes, AllAtOnce]
Alarms: [!Ref ErrorsAlarm]
Policies: [DynamoDBCrudPolicy: {TableName: !Ref NotesTable}]
Events:
Create: {Type: HttpApi, Properties: {ApiId: !Ref Api, Path: /notes, Method: POST}}
List: {Type: HttpApi, Properties: {ApiId: !Ref Api, Path: /notes, Method: GET}}
Get: {Type: HttpApi, Properties: {ApiId: !Ref Api, Path: '/notes/{id}', Method: GET}}
Update: {Type: HttpApi, Properties: {ApiId: !Ref Api, Path: '/notes/{id}', Method: PUT}}
Delete: {Type: HttpApi, Properties: {ApiId: !Ref Api, Path: '/notes/{id}', Method: DELETE}}
ErrorsAlarm:
Type: AWS::CloudWatch::Alarm
Properties:
Namespace: AWS/Lambda
MetricName: Errors
Dimensions: [{Name: FunctionName, Value: !Ref NotesFunction}]
Statistic: Sum
Period: 60
EvaluationPeriods: 1
Threshold: 1
ComparisonOperator: GreaterThanOrEqualToThreshold
TreatMissingData: notBreaching
LogGroup:
Type: AWS::Logs::LogGroup
Properties:
LogGroupName: !Sub /aws/lambda/${NotesFunction}
RetentionInDays: 30
Outputs:
ApiUrl: {Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${Stage}'}
UserPoolId: {Value: !Ref UserPool}
ClientId: {Value: !Ref UserPoolClient}
Step 2: Handlers
python
# src/app.py
import json, os, time, uuid, logging
import boto3
from boto3.dynamodb.conditions import Key
from botocore.exceptions import ClientError
log = logging.getLogger(); log.setLevel(os.environ.get("LOG_LEVEL", "INFO"))
table = boto3.resource("dynamodb").Table(os.environ["TABLE"]) # created once per environment
def resp(code, body):
return {"statusCode": code, "headers": {"Content-Type": "application/json"}, "body": json.dumps(body)}
def parse(event):
try:
data = json.loads(event.get("body") or "{}")
except json.JSONDecodeError:
raise ValueError("body must be valid JSON")
title = (data.get("title") or "").strip()
text = (data.get("text") or "").strip()
if not title or len(title) > 100:
raise ValueError("title is required (1-100 characters)")
if len(text) > 5000:
raise ValueError("text must be at most 5000 characters")
return {"title": title, "text": text}
def create(user, event):
note = parse(event)
key = (event.get("headers") or {}).get("idempotency-key")
note_id = f"{int(time.time()*1000)}-{uuid.uuid4().hex[:6]}"
if key: # same key = same note, even on retry
note_id = f"idem-{key}"
item = {"userId": user, "noteId": note_id, "createdAt": int(time.time()), **note}
try:
table.put_item(Item=item, ConditionExpression="attribute_not_exists(noteId)")
except ClientError as e:
if e.response["Error"]["Code"] != "ConditionalCheckFailedException":
raise
item = table.get_item(Key={"userId": user, "noteId": note_id})["Item"] # replay: return the original
return resp(201, item)
def list_notes(user, event):
qs = event.get("queryStringParameters") or {}
kw = {"KeyConditionExpression": Key("userId").eq(user), "Limit": min(int(qs.get("limit", 20)), 100), "ScanIndexForward": False}
if qs.get("next"):
kw["ExclusiveStartKey"] = {"userId": user, "noteId": qs["next"]}
r = table.query(**kw)
last = r.get("LastEvaluatedKey")
return resp(200, {"items": r["Items"], "next": last["noteId"] if last else None})
def get_note(user, event):
r = table.get_item(Key={"userId": user, "noteId": event["pathParameters"]["id"]})
return resp(200, r["Item"]) if "Item" in r else resp(404, {"error": "not found"})
def update(user, event):
note = parse(event)
try:
r = table.update_item(Key={"userId": user, "noteId": event["pathParameters"]["id"]},
UpdateExpression="SET title = :t, #tx = :x", ExpressionAttributeNames={"#tx": "text"},
ExpressionAttributeValues={":t": note["title"], ":x": note["text"]},
ConditionExpression="attribute_exists(noteId)", ReturnValues="ALL_NEW")
except ClientError as e:
if e.response["Error"]["Code"] == "ConditionalCheckFailedException":
return resp(404, {"error": "not found"})
raise
return resp(200, r["Attributes"])
def delete(user, event):
table.delete_item(Key={"userId": user, "noteId": event["pathParameters"]["id"]})
return {"statusCode": 204}
ROUTES = {"POST /notes": create, "GET /notes": list_notes, "GET /notes/{id}": get_note,
"PUT /notes/{id}": update, "DELETE /notes/{id}": delete}
def handler(event, context):
user = event["requestContext"]["authorizer"]["jwt"]["claims"]["sub"] # from the verified token, never from the body
fn = ROUTES.get(event["routeKey"])
if not fn:
return resp(404, {"error": "route not found"})
try:
return fn(user, event)
except ValueError as e:
return resp(400, {"error": str(e)})
except Exception:
log.exception("unhandled error")
return resp(500, {"error": "internal error"})
- The owner is always the partition key from the token, so one user can never reach another user's items
- Conditional writes protect against duplicates and updates to missing notes
- The 500 response hides internals while
log.exceptionkeeps the details in logs and traces
Step 3: Unit Tests
python
# tests/unit/test_app.py
import json, importlib, boto3, pytest
from moto import mock_aws
@pytest.fixture
def app(monkeypatch):
monkeypatch.setenv("AWS_DEFAULT_REGION", "ap-south-1")
monkeypatch.setenv("AWS_ACCESS_KEY_ID", "x"); monkeypatch.setenv("AWS_SECRET_ACCESS_KEY", "x")
monkeypatch.setenv("TABLE", "notes")
with mock_aws():
boto3.resource("dynamodb").create_table(TableName="notes", BillingMode="PAY_PER_REQUEST",
KeySchema=[{"AttributeName": "userId", "KeyType": "HASH"}, {"AttributeName": "noteId", "KeyType": "RANGE"}],
AttributeDefinitions=[{"AttributeName": "userId", "AttributeType": "S"}, {"AttributeName": "noteId", "AttributeType": "S"}])
import src.app as a
importlib.reload(a)
yield a
def ev(route, user="u1", body=None, path=None, headers=None):
return {"routeKey": route, "body": json.dumps(body) if body else None, "pathParameters": path,
"headers": headers or {}, "requestContext": {"authorizer": {"jwt": {"claims": {"sub": user}}}}}
def test_create_and_list(app):
r = app.handler(ev("POST /notes", body={"title": "Hello", "text": "x"}), None)
assert r["statusCode"] == 201
items = json.loads(app.handler(ev("GET /notes"), None)["body"])["items"]
assert len(items) == 1
def test_user_isolation(app):
app.handler(ev("POST /notes", user="alice", body={"title": "Secret"}), None)
assert json.loads(app.handler(ev("GET /notes", user="bob"), None)["body"])["items"] == []
def test_idempotent_create(app):
h = {"idempotency-key": "k1"}
a = app.handler(ev("POST /notes", body={"title": "T"}, headers=h), None)
b = app.handler(ev("POST /notes", body={"title": "T"}, headers=h), None)
assert json.loads(a["body"])["noteId"] == json.loads(b["body"])["noteId"]
def test_validation(app):
assert app.handler(ev("POST /notes", body={"title": ""}), None)["statusCode"] == 400
Step 4: Build, Deploy and Try It
bash
pip install pytest moto boto3 && pytest tests/unit -q
sam validate --lint && sam build
sam deploy --guided --stack-name notes-dev --parameter-overrides Stage=dev --capabilities CAPABILITY_IAM
API=$(aws cloudformation describe-stacks --stack-name notes-dev --query "Stacks[0].Outputs[?OutputKey=='ApiUrl'].OutputValue" --output text)
aws cognito-idp sign-up --client-id $CLIENT --username me@example.com --password 'Str0ng!Passw0rd'
aws cognito-idp admin-confirm-sign-up --user-pool-id $POOL --username me@example.com
TOKEN=$(aws cognito-idp initiate-auth --client-id $CLIENT --auth-flow USER_PASSWORD_AUTH --auth-parameters USERNAME=me@example.com,PASSWORD='Str0ng!Passw0rd' --query AuthenticationResult.IdToken --output text)
curl -s -X POST $API/notes -H "Authorization: $TOKEN" -H 'Idempotency-Key: demo-1' -d '{"title":"First","text":"hello"}'
curl -s "$API/notes?limit=5" -H "Authorization: $TOKEN"
curl -s -o /dev/null -w "%{http_code}\n" $API/notes # 401 without a toke
Step 5: CI/CD Pipeline
yaml
# buildspec.yml
version: 0.2
phases:
install:
runtime-versions: {python: 3.12}
commands: [pip install aws-sam-cli pytest moto boto3 cfn-lint]
build:
commands:
- cfn-lint template.yaml
- pytest tests/unit -q
- sam build
- sam package --s3-bucket $ARTIFACT_BUCKET --output-template-file packaged.yaml
artifacts:
files: [packaged.yaml]
- Source: GitHub through CodeConnections
- Build: the
buildspec.ymlabove - DeployTest: CloudFormation action creating stack
notes-testfrompackaged.yamlwithStage=test - IntegrationTest: CodeBuild project running
pytest tests/integrationwithAPI_URLfrom stack outputs - Approval: manual approval with SNS email
- DeployProd: same template with
Stage=produsing the canary setting and the error alarm for rollback
- Give the pipeline role only the permissions it needs (CloudFormation, IAM pass role for named roles, S3 artifacts)
- Keep a separate AWS account for prod if possible, with cross-account roles and a shared KMS key for artifacts
Step 6: Observe and Alert
- X-Ray shows API โ Lambda โ DynamoDB latency
- CloudWatch Logs Insights:
filter @message like /ERROR/ | stats count() by bin(5m) - Alarms: Lambda
Errors,Throttles,Durationp99, API5xx, DynamoDBThrottledRequests - Add a dashboard with requests, errors, latency and consumed capacity
Step 7: Harden
| Area | Action |
|---|---|
| Security | WAF on the API (rate limit), restrict CORS origins, short token lifetimes, KMS customer managed key for the table |
| Cost | Budget alarm, log retention, on-demand capacity, arm64 |
| Reliability | DLQ for any async parts, PITR on, load test for throttling |
| Operations | Runbook for rollback (aws lambda update-alias or redeploy), tags on all resources |
Cleanup
bash
sam delete --stack-name notes-test --no-prompts
sam delete --stack-name notes-dev --no-prompts
# the table has DeletionPolicy Retain: delete it manually if you no longer need the data
aws dynamodb delete-table --table-name <table-name>
Extensions
- Add a GSI and a
tagfilter endpoint - Add file attachments with S3 presigned URLs
- Add an SQS queue and worker to generate summaries with Bedrock
- Add an OpenAPI definition and generate a client
- Replace the Lambda for simple routes with direct API Gateway to DynamoDB integration and compare cost
Conclusion
You built a secured serverless API: Cognito JWT authorizer, Lambda handlers that trust only the token, a DynamoDB keyed by user, idempotent create, tested with moto, deployed with SAM through a CodePipeline that runs unit and integration tests, an approval gate and a canary release with alarm-based rollback, plus tracing, logs and alarms.
Quick Summary: goal; requirements; layout; SAM template; handlers; unit tests; deploy and try; pipeline; observe; harden; cleanup.

