Case Studies & Reference Builds Best Practices

This is the checklist to run against any end-to-end build, whether it is one from this section or your own.

Each item is a rule stated positively, with a one-line rationale. The groups run from wiring outward to resilience, cost, and rollout - the order a new build's decisions tend to get made in.

How to Use This List

Treat each box as an audit question against your own reference build, not just the four in this section.
Read the groups in order: wiring decisions come first, then resilience, then cost, then rollout.
Most rules apply across every build shape - request-driven, event-driven, or batch - even though the examples lean on this section's four case studies.
Revisit the list whenever you add a new service to an existing build, since new wiring reintroduces the same risks.

A - Wiring & Architecture

Keep the trigger thin. A function invoked by an event (API Gateway, S3, EventBridge) should translate the event and hand off, not perform the whole workflow itself.
Let orchestration own multi-step workflows. Step Functions, not a chain of Lambda calls, should decide what runs next and how failures branch.
Match the API Gateway type to the need. HTTP API for a simple proxy; REST API only when you need its extra features (usage plans, request validation, private endpoints).
Separate the reusable plumbing from the domain logic. Retry, idempotency, and error handling belong in every build; keep them visibly apart from what varies per project.

# --- Python (boto3) ---
# Thin trigger: translate the event, hand off to orchestration, return.
def handler(event, context):
    record = event["Records"][0]["s3"]
    sfn.start_execution(
        stateMachineArn=STATE_MACHINE_ARN,
        input=json.dumps({"bucket": record["bucket"]["name"], "key": record["object"]["key"]}),
    )

// --- TypeScript (AWS SDK v3) ---
// Thin trigger: translate the event, hand off to orchestration, return.
export const handler = async (event: any) => {
  const record = event.Records[0].s3;
  await sfn.send(new StartExecutionCommand({
    stateMachineArn: STATE_MACHINE_ARN,
    input: JSON.stringify({ bucket: record.bucket.name, key: record.object.key }),
  }));
};

B - Resilience

Batch before you add retries. A batched call that occasionally throttles is a smaller problem than a per-item loop that throttles on every hundredth call.
Decouple slow downstream calls from the write path. Move notification, indexing, or audit logging behind a queue rather than calling them inline.
Make every handler idempotent. Lambda, SQS, and S3 events are all at-least-once by default - a retried or duplicate delivery must be safe.
Set bounded retry with backoff on every client. Never leave retry unbounded, and never leave it unset.
Add explicit Catch/error branches in orchestration. A workflow with no failure path fails silently instead of surfacing where it broke.

C - Cost & Scale Shape

State the cost shape of a build honestly. Per-request billing on serverless components means cost grows with traffic - say so, don't imply a demo's cost holds at scale.
Prefer managed retrieval/orchestration over hand-rolled loops. RetrieveAndGenerate, Step Functions SDK integrations, and DynamoDB batch writers exist specifically to avoid reinventing this layer.
Hedge fast-moving surfaces explicitly. Call out where a service (S3 Vectors is the clear 2026 example) is still evolving, rather than presenting a moving target as settled.
Right-size batch sizes to each service's limits. 25 for DynamoDB BatchWriteItem, 10 for SQS SendMessageBatch - chunk larger lists rather than assuming an unlimited batch.

D - Rollout & Verification

Roll out architecture changes behind a flag or canary. Compare error rates and latency between old and new paths before a full cutover.
Test failure branches in CI, not just the happy path. A pipeline that never exercises a 404, a conflict, or a catch branch ships untested error handling.
Verify cross-service permissions before relying on them. A missing resource-based policy (Lambda-to-API-Gateway, S3-to-Lambda) is a common first failure in a new build.
Measure before and after a refactor. Round trips per batch, p50/p99 latency, and throttling rate tell you whether a change actually helped.

FAQs

Which of these practices matters most when starting a new build?

Keep the trigger thin and let orchestration own the workflow. Most of the resilience problems in this section's before/after case study trace back to a trigger that tried to do too much itself.

Do these practices apply to non-serverless builds too?

Mostly yes. Idempotency, bounded retry with backoff, decoupling slow downstream calls, and honest cost accounting apply whether the compute is Lambda, ECS, or EC2. The trigger-thinness rule is most relevant to event-driven serverless designs specifically.

Why is idempotency called out as a default requirement, not a nice-to-have?

Because Lambda, SQS, and S3 event delivery are all at-least-once by default across AWS. A handler that assumes exactly-once delivery will eventually double-process something, so idempotency has to be designed in from the start, not added after an incident.

How do I decide between hand-rolling a retry loop and using a managed integration?

Prefer the managed path (RetrieveAndGenerate, Step Functions SDK integrations, batch writers) whenever it covers your case - it has already solved the retry, backoff, and partial-failure handling you would otherwise reimplement.

What does "hedge fast-moving surfaces" mean in practice?

For a service whose API is still changing, like S3 Vectors in 2026, state plainly that field names and shapes may shift, and point to the service's own section for the current details, rather than presenting example code as permanently accurate.

How should I verify a build's cross-service permissions before shipping?

Test the actual invocation path end to end - an S3 event reaching Lambda, or API Gateway reaching Lambda - rather than assuming a resource-based policy is correct because the IAM role looks right. Missing invoke permissions are a common first failure and are easy to miss by reading policy JSON alone.

What should I measure to know a refactor actually helped?

Round trips per unit of work, p50/p99 latency, and throttling/error rate, compared before and after under representative load - not just a smaller code diff or a cleaner architecture diagram.

What Makes a Good AWS SDK Reference Build - the criteria these practices are drawn from.
Before/After: Refactoring a Monolithic SDK Integration - the full case study behind groups A and B.
Building a Data Pipeline: S3 + Lambda + Step Functions + Redshift - the thin-trigger, orchestration-owns-the-workflow pattern in group A.
Core AWS Services Best Practices - the underlying per-service habits these build-level practices assume.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Case Studies & Reference Builds Best Practices

This is the checklist to run against any end-to-end build, whether it is one from this section or your own.

Each item is a rule stated positively, with a one-line rationale. The groups run from wiring outward to resilience, cost, and rollout - the order a new build's decisions tend to get made in.

How to Use This List

Treat each box as an audit question against your own reference build, not just the four in this section.
Read the groups in order: wiring decisions come first, then resilience, then cost, then rollout.
Most rules apply across every build shape - request-driven, event-driven, or batch - even though the examples lean on this section's four case studies.
Revisit the list whenever you add a new service to an existing build, since new wiring reintroduces the same risks.

A - Wiring & Architecture

Keep the trigger thin. A function invoked by an event (API Gateway, S3, EventBridge) should translate the event and hand off, not perform the whole workflow itself.
Let orchestration own multi-step workflows. Step Functions, not a chain of Lambda calls, should decide what runs next and how failures branch.
Match the API Gateway type to the need. HTTP API for a simple proxy; REST API only when you need its extra features (usage plans, request validation, private endpoints).
Separate the reusable plumbing from the domain logic. Retry, idempotency, and error handling belong in every build; keep them visibly apart from what varies per project.

# --- Python (boto3) ---
# Thin trigger: translate the event, hand off to orchestration, return.
def handler(event, context):
    record = event["Records"][0]["s3"]
    sfn.start_execution(
        stateMachineArn=STATE_MACHINE_ARN,
        input=json.dumps({"bucket": record["bucket"]["name"], "key": record["object"]["key"]}),
    )

// --- TypeScript (AWS SDK v3) ---
// Thin trigger: translate the event, hand off to orchestration, return.
export const handler = async (event: any) => {
  const record = event.Records[0].s3;
  await sfn.send(new StartExecutionCommand({
    stateMachineArn: STATE_MACHINE_ARN,
    input: JSON.stringify({ bucket: record.bucket.name, key: record.object.key }),
  }));
};

B - Resilience

Batch before you add retries. A batched call that occasionally throttles is a smaller problem than a per-item loop that throttles on every hundredth call.
Decouple slow downstream calls from the write path. Move notification, indexing, or audit logging behind a queue rather than calling them inline.
Make every handler idempotent. Lambda, SQS, and S3 events are all at-least-once by default - a retried or duplicate delivery must be safe.
Set bounded retry with backoff on every client. Never leave retry unbounded, and never leave it unset.
Add explicit Catch/error branches in orchestration. A workflow with no failure path fails silently instead of surfacing where it broke.

C - Cost & Scale Shape

State the cost shape of a build honestly. Per-request billing on serverless components means cost grows with traffic - say so, don't imply a demo's cost holds at scale.
Prefer managed retrieval/orchestration over hand-rolled loops. RetrieveAndGenerate, Step Functions SDK integrations, and DynamoDB batch writers exist specifically to avoid reinventing this layer.
Hedge fast-moving surfaces explicitly. Call out where a service (S3 Vectors is the clear 2026 example) is still evolving, rather than presenting a moving target as settled.
Right-size batch sizes to each service's limits. 25 for DynamoDB BatchWriteItem, 10 for SQS SendMessageBatch - chunk larger lists rather than assuming an unlimited batch.

D - Rollout & Verification

Roll out architecture changes behind a flag or canary. Compare error rates and latency between old and new paths before a full cutover.
Test failure branches in CI, not just the happy path. A pipeline that never exercises a 404, a conflict, or a catch branch ships untested error handling.
Verify cross-service permissions before relying on them. A missing resource-based policy (Lambda-to-API-Gateway, S3-to-Lambda) is a common first failure in a new build.
Measure before and after a refactor. Round trips per batch, p50/p99 latency, and throttling rate tell you whether a change actually helped.

FAQs

Which of these practices matters most when starting a new build?

Keep the trigger thin and let orchestration own the workflow. Most of the resilience problems in this section's before/after case study trace back to a trigger that tried to do too much itself.

Do these practices apply to non-serverless builds too?

Why is idempotency called out as a default requirement, not a nice-to-have?

How do I decide between hand-rolling a retry loop and using a managed integration?

What does "hedge fast-moving surfaces" mean in practice?

How should I verify a build's cross-service permissions before shipping?

What should I measure to know a refactor actually helped?

Round trips per unit of work, p50/p99 latency, and throttling/error rate, compared before and after under representative load - not just a smaller code diff or a cleaner architecture diagram.

What Makes a Good AWS SDK Reference Build - the criteria these practices are drawn from.
Before/After: Refactoring a Monolithic SDK Integration - the full case study behind groups A and B.
Building a Data Pipeline: S3 + Lambda + Step Functions + Redshift - the thin-trigger, orchestration-owns-the-workflow pattern in group A.
Core AWS Services Best Practices - the underlying per-service habits these build-level practices assume.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Case Studies & Reference Builds Best Practices

Buscar en la documentación

Case Studies & Reference Builds Best Practices