200 the data is already durable. Do the clever work later, asynchronously, off the hot path.The problem with "Lambda as glue"
The default serverless API looks like API Gateway → Lambda → DynamoDB. For many endpoints the function in the middle does three things: parse JSON, check a field, call PutItem. That is code you now own: a runtime to upgrade, a deployment package, an IAM role, cold starts, concurrency limits, logs to pay for, and one more place for a bug to drop data on the floor.
A storage-first API flips the order. The request is persisted first, by a managed service, using a direct service integration. Processing (enrichment, emails, analytics) happens afterwards, triggered by the stored data. If the processing breaks, nothing is lost: the record is already there, waiting.
The wiring
How the newsletter does it
1. Same origin through CloudFront
The site and the API share serverlesssociety.com. A CloudFront cache behavior sends /api/* to the API Gateway origin with caching disabled; everything else goes to S3. The browser never makes a cross-origin call, so there is no CORS configuration to get wrong.
2. Validate at the gateway
A JSON Schema model is attached to the method with a request validator. Anything that isn't {"email": "…"} with a sane address is rejected with a 400 before any backend is called. The pattern is deliberately strict (no quotes, backslashes or spaces), which also means nothing awkward can reach the mapping template.
3. Map the request to PutItem
An AWS integration calls dynamodb:PutItem using an IAM role that can do exactly that, on exactly one table. A small VTL template builds the item:
#set($email = $input.path('$.email').trim().toLowerCase())
{
"TableName": "${SubscribersTable}",
"Item": {
"email": {"S": "$email"},
"createdAt": {"N": "$context.requestTimeEpoch"},
"status": {"S": "pending"},
"source": {"S": "site"}
},
"ConditionExpression": "attribute_not_exists(email)"
}
4. Idempotent by key, private by design
The email is the partition key and the write is conditional, so signing up twice can never create two rows. DynamoDB answers a duplicate with a 400 ConditionalCheckFailedException; the integration response turns that into the same {"ok":true} a new sign-up gets. The endpoint never reveals whether an address is already on the list. Any other 4xx from DynamoDB would be our bug, so it is overridden to a 500. (One gotcha: integration responses are keyed by status code, so this mapping is registered under 400 and sets the real status itself. Register two responses as 200 and the second silently replaces the first, which is exactly how our first deploy turned every new sign-up into a 500.)
#set($t = "$input.path('$.__type')")
#if($t.contains("ConditionalCheckFailed"))
#set($context.responseOverride.status = 200)
{"ok":true}
#else
#set($context.responseOverride.status = 500)
{"ok":false,"error":"server"}
#end
5. Throttle at the edge
The stage caps the API at 5 requests per second (burst 10). A bot hammering the form gets 429s from API Gateway, which costs it effort and costs us nothing in DynamoDB. The form also carries a hidden honeypot field that real people never fill in.
Control plane vs data plane
| Plane | What | Who calls it |
|---|---|---|
| control | Create the table, API, model, validator, IAM role, stage, CloudFront behavior | A human running a CloudFormation change set, rarely |
| data | POST /api/subscribe → dynamodb:PutItem | Every visitor, on every sign-up |
At run time the sign-up path depends only on data-plane APIs. If a control-plane API in the region has a bad day, sign-ups keep working: that's static stability, for free.
The template
All of it lives in infra/site.yaml, next to the bucket and distribution. The essential resources:
SubscribersTable: # PAY_PER_REQUEST, PITR on, key = email
Type: AWS::DynamoDB::Table
NewsletterApiRole: # apigateway.amazonaws.com may dynamodb:PutItem on that table only
Type: AWS::IAM::Role
NewsletterApi: # REGIONAL REST API (HTTP APIs can't integrate with DynamoDB directly)
Type: AWS::ApiGateway::RestApi
SubscribeModel + BodyValidator
SubscribeMethod: # POST /api/subscribe, Integration Type AWS -> dynamodb:action/PutItem
Type: AWS::ApiGateway::Method
NewsletterStage: # prod, throttled to 5 rps / burst 10
Type: AWS::ApiGateway::Stage
Distribution: # + origin "newsletter-api" and cache behavior /api/*
Type: AWS::CloudFront::Distribution
Try it yourself (a duplicate gives the same answer):
curl -s https://serverlesssociety.com/api/subscribe \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com"}'
# {"ok":true}
What it costs
Per sign-up: one REST API request and one on-demand DynamoDB write (an item this small is 1 write request unit). At us-east-1 list prices at the time of writing, that is about $3.50 per million API calls plus about $0.63 per million writes, so roughly $0.004 per thousand sign-ups, plus pennies for storage and point-in-time recovery. Nothing runs, and nothing bills, while nobody is signing up. Check the current API Gateway and DynamoDB pricing pages for your region.
Well-Architected checklist
- Operational excellence: everything in one CloudFormation template, changed through reviewed change sets; no console clicks.
- Security: the API role can call one action on one table; input validated before it reaches the backend; same-origin, HTTPS only; the response doesn't leak list membership.
- Reliability: no function to fail, time out or cold-start; conditional writes make retries safe; point-in-time recovery on the table.
- Performance efficiency: one network hop from gateway to table; no glue compute.
- Cost optimization: pay per request, zero idle cost, throttling caps abuse.
- Sustainability: no always-on or per-request compute; shared, highly utilized managed fleets do the work.
When not to do this
- You need logic before the write (calling another API, complex validation, fan-out to several stores). Put SQS in front instead (
API Gateway → SQS, also storage-first) and process from the queue. - VTL gets long. Mapping templates are fine for a few lines and painful for fifty. If you're writing loops in VTL, you wanted a function.
- You need a synchronous answer computed from the data. Storage-first acknowledges receipt, not results; clients poll or get notified later.
What's next for this one
Sign-ups are stored with status: "pending". The next step is double opt-in: DynamoDB Streams triggers a small function that sends a confirmation email through SES, and a confirm link flips the status. That processing is asynchronous, so if it breaks, nobody's sign-up is lost. Read part two: double opt-in without a mail server →