Serverless API With Lambda And DynamoDB

1. Situation

A mobile shopping application needs a cart API. Its important operations are predictable:

GET    /carts/{userId}
POST   /carts/{userId}/items
DELETE /carts/{userId}/items/{productId}

Traffic is quiet overnight and rises sharply during promotions. The team wants to spend its time on application behavior rather than operating web servers, load balancers, database hosts, and scaling groups.

The client expects an immediate answer. When it adds an item, it needs to know whether that request succeeded. This is a synchronous request-response path:

client sends request -> backend performs short work -> client receives response

The data also fits a clear access pattern. Most requests know the userId and need that user's cart. The application does not need arbitrary joins across customers, products, payments, and reports during every cart request.

This makes a serverless API worth considering.

The design question is:

How can the API scale with uneven traffic without replacing server operations with hidden data and retry problems?

2. Naive Design

Naive option 1: keep a web server running for a mostly quiet API

flowchart LR
  Client["Mobile client"] --> EC2["EC2 API server<br/>always running"]
  EC2 --> DB["Database"]

This architecture can be correct, especially for steady workloads or applications that need long-running processes. For a small, uneven API, it creates patching, deployment, capacity, and availability work before the first cart request is handled.

Naive option 2: move everything into one giant Lambda function

ANY /{route} -> one Lambda -> every table and secret

There are no application servers, but unrelated routes now share code, permissions, deployment risk, and scaling behavior. A bug in an admin route can affect the public cart path. The function's role often becomes broader than necessary.

Naive option 3: create a DynamoDB table before defining the reads

The team stores cart items with generated IDs and later asks DynamoDB to find all items for a user through a broad scan.

That reverses the useful design order:

unhealthy: create table -> store items -> discover queries later
healthy:   list access patterns -> design keys -> store items

DynamoDB is managed, but it cannot invent an efficient key for a query the team never modeled.

3. What Breaks

Follow four failure stories.

Failure 1: the client retries an uncertain write

The client sends POST /carts/user-42/items. The write succeeds, but the response is lost. The client retries and the application adds the same item twice.

The architecture needs an idempotency strategy or a conditional update that makes a repeated request safe.

Failure 2: one key receives disproportionate traffic

The team uses the same partition key value for every active cart. A promotion drives many reads and writes to that small key space.

The table may be serverless, but concentrated access can still create hot-key pressure. The architecture needs a partition-key design that matches the distribution of real traffic.

Failure 3: automatic scaling overwhelms a dependency

Lambda adds concurrent executions as requests rise. A downstream API accepts only a small number of connections, so scaling the function makes the dependency fail faster.

The architecture needs throttling and concurrency boundaries, not unlimited fan-out.

Failure 4: long work remains inside the client request

The function calls several slow services, generates a report, and sends emails while the mobile client waits. The request hits a timeout boundary, even though some backend work continues or has already succeeded.

Short request-time work belongs on the synchronous path. Long or independently retryable work belongs behind a queue, event, or workflow.

4. AWS Architecture

Build the API one responsibility at a time.

Step 1: define the public API contract with API Gateway

API Gateway becomes the managed HTTPS entry point. A route combines an HTTP method and path, such as POST /carts/{userId}/items, with the backend integration that handles it.

flowchart LR
  Client["Mobile client"] -->|"HTTPS"| API["API Gateway<br/>routes and API boundary"]

Choose the API Gateway product from required features:

• Choose an HTTP API when its simpler, lower-cost feature set covers the routes, integrations, and authorization model.
• Choose a REST API when the requirement calls for REST API features such as API keys and usage plans, request validation, API Gateway caching, private API endpoints, transformations, or direct WAF integration.

The phrase "RESTful endpoint" does not by itself force the API Gateway REST API product. Review API Gateway REST API vs HTTP API for the detailed feature comparison.

Step 2: run short request logic in Lambda

Connect each route, or a small related group of routes, to a Lambda function with a clear responsibility.

flowchart LR
  Client["Client"] --> API["API Gateway route"]
  API -->|"Synchronous invocation"| Lambda["Lambda function<br/>cart operation"]
  Lambda -->|"HTTP-shaped result"| API --> Client

For the normal API Gateway-Lambda path, the client waits for the Lambda response. If the invocation or function fails, API Gateway returns an error; it does not automatically retry that Lambda invocation for the client.

That distinction matters. Client retry policy and write idempotency remain application decisions.

Lambda is appropriate when the work fits its execution model and can finish within the request's latency and timeout boundaries. A queue or workflow is a better home for work that should continue independently after the API acknowledges it.

Step 3: design DynamoDB from access patterns

Write down the requests before creating the table:

A simple item shape might be:

PK = USER#42
SK = ITEM#product-9
quantity = 2

flowchart LR
  Lambda["Cart Lambda"] -->|"Get, Put, Update by key"| Table["DynamoDB table<br/>known access patterns"]
  Key["PK: user<br/>SK: cart item"] -.->|"Distributes and locates items"| Table

The partition key helps DynamoDB distribute and locate data. An optional sort key groups related items within that partition and provides ordered or exact item access.

A Global Secondary Index adds an alternate key-based access pattern. It is not a free escape hatch for every future query: it adds storage, write work, cost, and its own key-design considerations.

Choose RDS or Aurora instead when relational joins, flexible SQL, and relational transactions are central requirements rather than exceptions.

Step 4: separate client identity from function identity

There are two different trust questions:

May this client call the API?
May this Lambda function call DynamoDB?

API Gateway authorization answers the first question through the selected pattern, such as IAM, a JWT authorizer, Cognito, or a Lambda authorizer.

The Lambda execution role answers the second. Grant the cart function only the DynamoDB actions and resources it requires. API authorization does not automatically give the function database permission, and the execution role does not authenticate the mobile user.

flowchart LR
  Identity["Client identity<br/>authorizer"] -.->|"May call route?"| API["API Gateway"]
  API --> Lambda["Lambda"]
  Role["Execution role<br/>AWS permissions"] -.->|"May call table?"| Lambda
  Lambda --> Table["DynamoDB"]

Step 5: make repeated writes safe

Give a create-style request an idempotency key, such as an operation ID generated by the client. Store or enforce that key with a DynamoDB conditional write so the same logical operation cannot be applied twice accidentally.

first request with operation-abc  -> condition passes -> write succeeds
retry with operation-abc          -> already recorded -> return prior outcome

Conditional writes can also protect against lost updates by changing an item only when its version or current value matches what the application expects.

Idempotency does not mean "ignore every duplicate." It means repeated delivery of the same logical request produces one intended business effect.

Step 6: protect each capacity boundary

Use the controls for the pressure they actually manage:

• API Gateway throttling limits how quickly requests enter the API path.
• Lambda reserved concurrency can reserve capacity for a function and cap how much concurrency it consumes.
• DynamoDB on-demand capacity reduces capacity planning for uneven traffic.
• Provisioned capacity with auto scaling can fit predictable traffic that benefits from tuning.

These controls do not replace good keys. A bad hot key remains a concentrated access pattern even when the table uses on-demand capacity.

Step 7: add recovery and observability

Enable DynamoDB point-in-time recovery when accidental writes or deletes require historical restoration. PITR restores into a new table; it does not silently rewind the production table in place.

Use CloudWatch to connect the full request path:

• API Gateway latency, integration latency, 4XX, and 5XX responses;
• Lambda duration, errors, throttles, and concurrency;
• DynamoDB throttling, consumed capacity, and system errors; and
• application-level outcomes such as successful cart updates.

The completed architecture is:

flowchart LR
  Client["Web or mobile client"] -->|"HTTPS request"| API["API Gateway<br/>authorization and throttling"]
  API -->|"Synchronous invocation"| Lambda["Lambda<br/>request logic"]
  Lambda -->|"Key-based operation"| DB["DynamoDB<br/>cart state"]
  Role["Lambda execution role"] -.->|"Least-privilege AWS access"| Lambda
  PITR["Point-in-time recovery"] -.->|"Historical restore protection"| DB
  Observe["CloudWatch"] -.->|"Metrics, logs, and alarms"| API
  Observe -.-> Lambda
  Observe -.-> DB

5. Request Or Data Flow

Learn three flows: a read, a retry-safe write, and work that leaves the request path.

Flow 1: read the cart

1. The client sends GET /carts/user-42 with its authentication token.
2. API Gateway authorizes the client and matches the route.
3. API Gateway invokes the cart-reading Lambda function synchronously.
4. Lambda uses its execution role to query the USER#42 partition.
5. DynamoDB returns the matching items.
6. Lambda formats the response, and API Gateway returns it to the client.

Flow 2: retry-safe cart update

sequenceDiagram
  participant Client
  participant API as API Gateway
  participant Fn as Lambda
  participant DB as DynamoDB

  Client->>API: POST item with operation ID
  API->>Fn: Invoke synchronously
  Fn->>DB: Conditional write
  DB-->>Fn: Written or already applied
  Fn-->>API: Stable business response
  API-->>Client: HTTP result

If the response is lost and the client repeats the same operation ID, the function can recognize the same logical request rather than applying a second business effect.

Flow 3: accept long-running work

Suppose the user asks the API to generate a large cart export. Do not keep the HTTP request open while Lambda performs every step.

1. Validate and authorize the request.
2. Create a job record.
3. Send work to SQS, EventBridge, or Step Functions according to the communication shape.
4. Return an accepted response with a job identifier.
5. Let the client check status or receive a later notification.

The next scenario develops those asynchronous choices.

6. Security Controls

Authenticate the client at the API boundary

Choose an authorization mechanism that fits the caller. Do not treat an API key as user authentication; API keys are primarily associated with identification, metering, and usage-plan behavior in REST APIs.

Give each function a narrow execution role

A cart reader may need GetItem and Query. A cart writer may need selected write actions. Neither automatically needs permission to delete the table, read unrelated secrets, or access every DynamoDB table.

Validate at the application boundary

Authorization answers whether the caller may use the operation. Validation still checks path parameters, payload shape, quantities, allowed fields, and business rules. DynamoDB's flexible attributes do not make malformed input safe.

Protect sensitive data and logs

DynamoDB encrypts data at rest. Choose a customer-managed KMS key when the requirement calls for customer control over key policy, rotation, or audit boundaries.

Do not log authentication tokens, secrets, or full sensitive request bodies. Apply deliberate CloudWatch log retention.

7. Resilience Controls

API Gateway, Lambda, and DynamoDB are managed regional services, but application correctness still determines whether the API is resilient.

Use bounded client retries with backoff for transient failures. Retry reads more freely than uncertain writes. Require idempotency for create-style operations that might be repeated.

Use conditional writes for conflict-sensitive updates. A condition can prevent one client from overwriting a value that changed after it was read.

Enable DynamoDB PITR for important tables and practice restoring into a new table. Recovery is incomplete until the application can validate and deliberately switch to restored data.

Use reserved concurrency when one function must not consume all shared Lambda concurrency or when a downstream dependency needs a ceiling. Remember that a ceiling can protect a dependency but can also create Lambda throttles, so alarm on both sides of the boundary.

For independently retryable work, place a durable asynchronous boundary such as SQS after the API. Do not expect the normal synchronous API Gateway invocation to behave like a queue.

8. Performance Controls

Measure latency by layer:

client-visible latency
  = API Gateway work
  + Lambda initialization and execution
  + DynamoDB calls
  + network and serialization time

Keep deployment packages and initialization work deliberate. Reuse SDK clients outside the handler when the runtime allows execution-environment reuse.

Provisioned concurrency can reduce Lambda initialization latency for paths with strict predictable latency needs, but it adds cost. It is a targeted response to a measured requirement, not a default checkbox for every function.

Design DynamoDB keys to spread real traffic. A table-wide average can look healthy while one key receives disproportionate requests.

Use GSIs only for real alternate queries. Use caching or DAX only when repeated reads and latency measurements justify another data layer.

9. Cost Controls

The bill follows several meters rather than one server:

• API Gateway request volume and API type;
• Lambda invocation count, duration, and configured memory;
• DynamoDB reads, writes, storage, indexes, backups, and capacity mode;
• CloudWatch logs, metrics, and retention;
• KMS requests, data transfer, and optional features.

HTTP APIs are often the cost-efficient choice when their features are sufficient. REST APIs are justified when their additional management capabilities satisfy a real requirement.

Choose DynamoDB on-demand for unknown or uneven traffic when low capacity-management effort matters. Consider provisioned capacity with auto scaling for predictable steady workloads where tuning is worth the effort.

Lambda memory also changes available CPU. More memory can sometimes finish work fast enough to lower total duration cost, so measure rather than assuming the smallest setting is cheapest.

Avoid verbose permanent logs for every successful request. Retain the information needed to investigate and operate the API, not an accidental second copy of every payload.

10. Exam Variants

11. Common Traps

Final Mental Model: One-Minute Review

flowchart LR
  Client["Client"] -->|"HTTPS request"| API["API Gateway<br/>routes and ingress controls"]
  API -->|"Synchronous invocation"| Lambda["Lambda<br/>on-demand request worker"]
  Lambda -->|"Key-based read or conditional write"| DB["DynamoDB<br/>keyed application state"]
  Auth["Authorizer<br/>client permission"] -.-> API
  Role["Execution role<br/>AWS permission"] -.-> Lambda
  Limits["Throttling and concurrency"] -.->|"Protect capacity boundaries"| API
  PITR["Point-in-time recovery"] -.->|"Historical restore"| DB

The synchronous path is API Gateway → Lambda → DynamoDB. The authorizer decides whether the client may enter; the execution role decides what Lambda may call; the key design decides whether DynamoDB can answer efficiently; idempotency makes retries safe.

12. Related Topics

Use Amazon API Gateway for routes, stages, endpoint types, authorization, and integrations. Review AWS Lambda for execution environments, concurrency, permissions, and invocation models. Use Amazon DynamoDB for deeper key, index, capacity, stream, and global-table design.

Continue to Event-Driven Order Processing when work must be routed, buffered, retried, or coordinated after the API returns.

Official AWS references:

• Choose between API Gateway REST APIs and HTTP APIs
• Handle Lambda errors with API Gateway
• Understanding Lambda concurrency
• Best practices for designing and using partition keys effectively
• DynamoDB condition expressions
• DynamoDB backup and restore