David Wells

Builder of things

Software architect
& product wrangler

Software architect & product wrangler

Idempotent Requests Demo

awsserverlessapi-designreliability

Idempotent Requests is a demo of retry-safe API behavior across client and server boundaries.

It explores how idempotency keys help systems handle retries without accidentally duplicating work.

Why it matters

Modern APIs are surrounded by retries: browsers retry, infrastructure retries, clients retry, and users retry. Idempotency turns that uncertainty into an explicit protocol.

Full documentation, synced from the package README:

A demonstration project showcasing how to implement idempotent requests in AWS Lambda functions using the AWS Lambda Powertools library. This project includes both backend and frontend components to demonstrate the complete flow of idempotent request handling.

Table of Contents

Project Structure

.
├── src/              # Source code for both frontend and backend
│   ├── backend/      # AWS Lambda functions and infrastructure
│   └── frontend/     # React frontend application
├── scripts/          # Utility scripts
└── docs/             # Project documentation

Prerequisites

  • Node.js (v18 or later)
  • pnpm (v10.11.0 or later)
  • AWS CLI configured with appropriate credentials

Setup

  1. Install dependencies:

In the root dir run:

# Install dependencies
npm run setup

  1. Configure AWS credentials:

    • Ensure you have AWS credentials configured in ~/.aws/credentials
    • The credentials should have permissions to create and manage DynamoDB tables and Lambda functions

  2. Deploy the backend:

cd src/backend
npm run deploy

Development

Backend

The backend consists of AWS Lambda functions that demonstrate idempotent request handling using AWS Lambda Powertools. Key features:

  • Idempotent request handling using DynamoDB
  • Structured logging
  • Unit and integration tests

To start the development server:

npm start

To run tests:

cd src/backend
pnpm run test

Frontend

The frontend is a React application that demonstrates how to interact with the idempotent API endpoints.

To start the development server:

cd src/frontend
npm start

Make sure to deploy the backend first to setup the API endpoint.

Pull in the backend api endpoint automatically with

cd src/frontend
npm run sync

Key Features

  • Idempotent request handling using AWS Lambda Powertools
  • DynamoDB integration for idempotency state management
  • Structured logging with AWS Lambda Powertools Logger
  • React frontend for demonstration
  • Comprehensive test suite

Architecture

The project uses:

  • AWS Lambda for serverless functions
  • DynamoDB for idempotency state management
  • @aws-lambda-powertools/idempotency for idempotency
  • React + vite for the frontend interface

License

ISC

Idempotent Requests Demo — live demoOpen full demo ↗View source