Project 1: Serverless REST API with API Gateway, Lambda, DynamoDB and Cognito, Deployed by a CI/CD Pipeline

AWS Developer Associate 70 min min read Updated: Nov 17, 2026 Intermediate
Project 1: Serverless REST API with API Gateway, Lambda, DynamoDB and Cognito, Deployed by a CI/CD Pipeline
Intermediate Topic 1 of 3

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
1POST /notes, GET /notes, GET /notes/{id}, PUT /notes/{id}, DELETE /notes/{id}
2Only the owner can read or change a note (user id from the verified token)
3Input validation, JSON errors, idempotent create using an Idempotency-Key header
4Pagination for the list endpoint
5Unit tests with moto, integration test against a real stack
6Canary deployment with automatic rollback on errors
7Logs, 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.exception keeps 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]
  1. Source: GitHub through CodeConnections
  2. Build: the buildspec.yml above
  3. DeployTest: CloudFormation action creating stack notes-test from packaged.yaml with Stage=test
  4. IntegrationTest: CodeBuild project running pytest tests/integration with API_URL from stack outputs
  5. Approval: manual approval with SNS email
  6. DeployProd: same template with Stage=prod using 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, Duration p99, API 5xx, DynamoDB ThrottledRequests
  • Add a dashboard with requests, errors, latency and consumed capacity

Step 7: Harden

AreaAction
SecurityWAF on the API (rate limit), restrict CORS origins, short token lifetimes, KMS customer managed key for the table
CostBudget alarm, log retention, on-demand capacity, arm64
ReliabilityDLQ for any async parts, PITR on, load test for throttling
OperationsRunbook 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

  1. Add a GSI and a tag filter endpoint
  2. Add file attachments with S3 presigned URLs
  3. Add an SQS queue and worker to generate summaries with Bedrock
  4. Add an OpenAPI definition and generate a client
  5. 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.

Get Newsletter

Subscibe to our newsletter and we will notify you about the newest updates on Edugators