AWS · Editable reference architecture

Serverless API Gateway Lambda DynamoDB

Design an AWS serverless API with a clear request path and a separate asynchronous processing path. Use API Gateway, Lambda and DynamoDB components to discuss authentication, data access, retry behavior and workload boundaries.

Open & Edit in DrawArc (Free, No Login Required)

Your changes stay in a separate draft on this browser. Download an editable project to keep a portable copy.

LinkedIn X (Twitter)WhatsApp

7 components · 7 connections · Open the editor to zoom, move nodes and edit source.

Architectural overview

A serverless API uses managed request routing and short-lived compute rather than requiring a permanently running application server. In this starter, clients send requests to API Gateway, which validates authorization before invoking Lambda. The request handler accesses DynamoDB for persistent state and can enqueue long-running work to SQS for a separate worker function.

The asynchronous path matters when a request should return before all processing completes. Define the meaning of an accepted response and how the client checks the eventual result. SQS delivery can repeat, so a worker should be idempotent and use bounded retries with a failure destination. A queue does not remove the need for capacity planning: concurrency, downstream throttling and database access patterns still limit throughput.

During implementation review, specify token validation, least-privilege permissions and how sensitive fields are logged. Design DynamoDB keys around known access patterns instead of assuming arbitrary relational queries will translate directly. Add timeouts, alarms and a recovery path for failed background work. Update the diagram to show any external payment, messaging or storage service so reviewers can assess dependencies beyond the managed AWS request path.

The real-world problem

A bursty API needs short authenticated request handling while long-running jobs continue asynchronously with visible completion state and controlled duplicate processing.

Data flow

Connections from this diagram. Branches and control signals are not a single chronological sequence.

API client → API Gateway: HTTPS.
API Gateway → Cognito authorizer: Validate identity.
API Gateway → Request Lambda: Invoke authorized request.
Request Lambda → DynamoDB: Read or write.
Request Lambda → SQS work queue: Enqueue job.
SQS work queue → Worker Lambda: Deliver job.
Worker Lambda → DynamoDB: Update result.

Security boundaries

Validate token issuer, audience and scopes; enforce record/tenant authorization inside the handler.
Give request and worker functions separate least-privilege roles for their DynamoDB and queue operations.
Validate payload size/schema, encrypt data and redact tokens and sensitive fields from logs.

Failure handling

SQS delivers a job more than once

Response: Use durable idempotency keyed to the business operation; acknowledge only after the intended side effect succeeds.

Verify: Deliver duplicates and simulate a crash between side effect and acknowledgement.

A batch contains a poison message

Response: Use partial batch failure handling where appropriate, bounded receive attempts and a configured dead-letter destination.

Verify: Mix valid and invalid records and check retries, alerts and controlled replay.

Concurrency overwhelms a dependency

Response: Set concurrency and throttling limits, queue-age alarms and a clear retry/acceptance contract for clients.

Verify: Load-test a burst and check backlog drain time and dependency saturation.

Trade-offs and alternatives

Buffer work in SQS

Benefit: Independent retries and burst absorption.
Cost: Eventual results, queue monitoring and duplicate delivery handling.
Alternative: Process synchronously only when work fits the latency budget and dependency limits.

Use DynamoDB access patterns

Benefit: Managed key-based reads and writes.
Cost: Key design, hot partitions and denormalization; arbitrary relational joins are not a drop-in operation.
Alternative: Evaluate a relational store when transactions and query relationships dominate.

When to use this architecture

Plan an API with bursty demand where managed routing and function execution fit the workload.
Separate short request handling from background jobs with explicit acceptance and retry semantics.
Review authorization, DynamoDB access patterns and downstream concurrency limits before provisioning resources.

Key components

API client: Sends authenticated requests and handles asynchronous job status.
API Gateway: Routes requests, applies limits and invokes authorization checks.
Cognito authorizer: Provides the identity validation boundary for protected API operations.
Request Lambda: Validates commands, reads or writes state and enqueues background work.
DynamoDB: Stores records designed around explicit partition and query access patterns.
SQS work queue: Buffers jobs and exposes retry and failure handling decisions.
Worker Lambda: Processes queued work idempotently with controlled concurrency.

Questions about this template

Is a serverless API always cheaper?

No. Cost depends on traffic, execution duration, data access and other managed services. Model your workload before choosing a deployment approach.

Can I remove the queue?

Yes, if all required work fits the synchronous request budget. Keep the queue when you need buffering, independent retries or longer-running work.

Related architecture templates

AWS