Pattern 01 · Resilience

Storage-first APIs: persist before you process

The newsletter form on this site has no Lambda function behind it. API Gateway validates the request and writes it straight into DynamoDB. Here is the whole thing: wiring, plane split, the real template, what it costs, and where it stops being the right tool.

Serverless Society · November 2026 · 7 min read

TL;DR. If a request only needs to be stored right now, let the managed front door store it. Fewer hops, nothing to patch or cold-start, and when the client gets a 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

Storage-first newsletter sign-up Browser posts to CloudFront at /api/subscribe. CloudFront forwards to API Gateway, which validates the body, throttles, and calls DynamoDB PutItem with a conditional write. Later, optional async processing reads from DynamoDB Streams. Browser POST /api/subscribe CloudFront same origin, no cache API Gateway validate body (model) throttle · map to PutItem DynamoDB conditional PutItem later, async: Streams → Lambda → SES welcome mail 200 = already durable
The hot path is three managed services and zero functions. The dashed box is optional, asynchronous, and can fail without losing a sign-up.

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

PlaneWhatWho calls it
controlCreate the table, API, model, validator, IAM role, stage, CloudFront behaviorA human running a CloudFormation change set, rarely
dataPOST /api/subscribe → dynamodb:PutItemEvery 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

When not to do this

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 →

Join the field notes →  ·  All posts