That\u2019s exactly what idempotency<\/strong> prevents.<\/p>\n\n\n\n
In distributed and cloud-native architectures, duplicate requests<\/strong> happen often:<\/p>\n\n\n\n An idempotent API<\/strong> guarantees that executing the same request multiple times produces the same result<\/strong> \u2014 no side effects, no duplicates, no surprises.<\/p>\n\n\n\n In this detailed tutorial, we\u2019ll build such an API using:<\/p>\n\n\n\n All source code is available on GitHub <\/a> Definition:<\/strong> Example:<\/p>\n\n\n\n So Our approach adds a lightweight Idempotency Layer<\/strong> on top of your API.<\/p>\n\n\n\n This pattern ensures the request can be safely retried<\/strong> without side effects.<\/p>\n\n\n\n Our solution consists of:<\/p>\n\n\n\n In your terminal:<\/p>\n\n\n\n This initializes a clean .NET 9 Minimal API project.<\/p>\n\n\n\n We\u2019ll persist payments and idempotent requests in SQLite.<\/p>\n\n\n\n Example: Payment Entity (simplified)<\/p>\n\n\n\n Each payment stores the key that triggered it \u2014 ensuring the same key cannot produce another row.<\/p>\n\n\n\n The store is the heart of the system. Simplified Logic<\/p>\n\n\n\n Each processed request is cached in-memory and persisted in the database for replay.<\/p>\n\n\n\n Let\u2019s modify our ✅ First call:<\/strong> creates and stores payment. Create a payment<\/p>\n\n\n\n \u2192 Returns same response<\/strong> \u2014 no duplicate row.<\/p>\n\n\n\n \u2192 Returns When clients or background workers call your API, transient failures can happen. Simple retry setup<\/p>\n\n\n\n Each retry uses the same Create a Then run:<\/p>\n\n\n\n Access it on http:\/\/localhost:8080\/payments<\/a><\/strong><\/p>\n\n\n\n GitHub Actions ensure the project builds and tests automatically.<\/p>\n\n\n\n Now each commit validates your solution.<\/p>\n\n\n\n In production, multiple API instances may run behind a load balancer. Simplified Flow Diagram<\/p>\n\n\n\n Every retry simply reads the stored result \u2014 simple, predictable, safe.<\/p>\n\n\n\n\n
\n
<\/p>\n\n\n\nWhat Is Idempotency?<\/h2>\n\n\n\n
\n
An operation is idempotent<\/em> if performing it multiple times has the same effect<\/strong> as doing it once.<\/p>\n<\/blockquote>\n\n\n\n\n
GET \/users\/5<\/code> \u2192 safe to call 100 times<\/li>\n\n\n\nPUT \/users\/5<\/code> with same data \u2192 always same outcome<\/li>\n\n\n\nDELETE \/users\/5<\/code> \u2192 deleting an already-deleted resource is harmless<\/li>\n\n\n\nPOST \/payments<\/code> \u2192 ⚠️ usually creates duplicates if repeated<\/li>\n<\/ul>\n\n\n\nPOST<\/code> operations must implement custom logic<\/strong> to become idempotent.
This is especially important for financial<\/strong>, order<\/strong>, and API-to-API<\/strong> systems.<\/p>\n\n\n\nSolution Overview<\/h2>\n\n\n\n
Architecture Summary<\/h3>\n\n\n\n
\n
Idempotency-Key<\/code> in the request header.<\/li>\n\n\n\n
\n\n\n\nProject Architecture<\/h2>\n\n\n\n
\n
OS.Tuto.IdempotentApi\/\n \u251c\u2500 Program.cs\n \u251c\u2500 Data\/\n \u2502 \u2514\u2500 AppDbContext.cs\n \u251c\u2500 Domain\/\n \u2502 \u251c\u2500 Payment.cs\n \u2502 \u2514\u2500 PaymentStatus.cs\n \u251c\u2500 Dtos\/\n \u2502 \u251c\u2500 PaymentRequest.cs\n \u2502 \u2514\u2500 PaymentResponse.cs\n \u251c\u2500 Idempotency\/\n \u2502 \u251c\u2500 IdempotencyRecord.cs\n \u2502 \u2514\u2500 IdempotencyStore.cs\n \u251c\u2500 Client\/\n \u2502 \u2514\u2500 Program.cs\n \u251c\u2500 Dockerfile\n \u251c\u2500 docker-compose.yml\n \u251c\u2500 appsettings.json\n \u2514\u2500 README.md\n<\/pre>\n\n\n\n
⚙️ Step 1 \u2014 Project Setup (.NET 9 Minimal API)<\/h2>\n\n\n\n
dotnet new web -n OS.Tuto.IdempotentApi\ncd OS.Tuto.IdempotentApi\ndotnet add package Microsoft.EntityFrameworkCore\ndotnet add package Microsoft.EntityFrameworkCore.Sqlite\ndotnet add package Microsoft.Extensions.Http.Resilience\n<\/pre>\n\n\n\n
\n\n\n\n⚙️ Step 2 \u2014 Add Database Context and Entities<\/h2>\n\n\n\n
AppDbContext<\/code><\/p>\n\n\n\npublic class AppDbContext : DbContext\n{\n public DbSet<Payment> Payments => Set<Payment>();\n public DbSet<IdempotencyRecord> IdempotencyRecords => Set<IdempotencyRecord>();\n public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }\n}\n<\/pre>\n\n\n\npublic class Payment\n{\n public Guid Id { get; set; } = Guid.NewGuid();\n public decimal Amount { get; set; }\n public string Currency { get; set; } = \"EUR\";\n public string Recipient { get; set; } = default!;\n public string IdempotencyKey { get; set; } = default!;\n public DateTime CreatedAtUtc { get; set; } = DateTime.UtcNow;\n}\n<\/pre>\n\n\n\n
\n\n\n\n⚙️ Step 3 \u2014 Implement the Idempotency Store<\/h2>\n\n\n\n
It remembers which keys were processed and what the API returned.<\/p>\n\n\n\npublic class IdempotencyStore\n{\n private readonly AppDbContext _db;\n private readonly IMemoryCache _cache;\n public IdempotencyStore(AppDbContext db, IMemoryCache cache)\n { _db = db; _cache = cache; }\n\n public async Task<(bool found, string response)> TryGetAsync(string key)\n {\n if (_cache.TryGetValue(key, out string body))\n return (true, body);\n\n var rec = await _db.IdempotencyRecords.FirstOrDefaultAsync(x => x.Key == key);\n return rec is null ? (false, \"\") : (true, rec.ResponseBody);\n }\n\n public async Task SaveAsync(string key, object response)\n {\n var json = JsonSerializer.Serialize(response);\n _db.IdempotencyRecords.Add(new() { Key = key, ResponseBody = json });\n await _db.SaveChangesAsync();\n _cache.Set(key, json);\n }\n}\n<\/pre>\n\n\n\n
\n\n\n\n⚙️ Step 4 \u2014 Make the POST Endpoint Idempotent<\/h2>\n\n\n\n
\/payments<\/code> endpoint to use Idempotency-Key<\/code>.<\/p>\n\n\n\napp.MapPost(\"\/payments\", async (PaymentRequest req, HttpContext ctx, AppDbContext db, IdempotencyStore store) =>\n{\n var key = ctx.Request.Headers[\"Idempotency-Key\"].FirstOrDefault();\n if (string.IsNullOrEmpty(key)) return Results.BadRequest(\"Missing Idempotency-Key\");\n\n var (found, body) = await store.TryGetAsync(key);\n if (found) return Results.Content(body, \"application\/json\");\n\n var payment = new Payment { Amount = req.Amount, Currency = req.Currency, Recipient = req.Recipient, IdempotencyKey = key };\n db.Payments.Add(payment);\n await db.SaveChangesAsync();\n\n var response = new { payment.Id, payment.Amount, payment.Recipient };\n await store.SaveAsync(key, response);\n\n return Results.Ok(response);\n});\n<\/pre>\n\n\n\n
✅ Repeated call with same key:<\/strong> returns same JSON response instantly.
⚠️ Same key + different body:<\/strong> can be handled as conflict (optional check).<\/p>\n\n\n\n
\n\n\n\n⚙️ Step 5 \u2014 Testing with Curl or Postman<\/h2>\n\n\n\n
curl -s http:\/\/localhost:5000\/payments \\\n -H \"Content-Type: application\/json\" \\\n -H \"Idempotency-Key: key-123\" \\\n -d '{\"amount\": 99.99, \"currency\": \"EUR\", \"recipient\": \"alice@example.com\"}'\n<\/pre>\n\n\n\nRe-run same request<\/h3>\n\n\n\n
Change payload, keep same key<\/h3>\n\n\n\n
409 Conflict<\/code> (optional validation step).<\/p>\n\n\n\n
\n\n\n\n⚙️ Step 6 \u2014 Safe Retry Using Polly v8<\/h2>\n\n\n\n
By combining Polly<\/strong> with our idempotent endpoint, retries become 100% safe<\/strong>.<\/p>\n\n\n\nbuilder.Services.AddHttpClient(\"PaymentsClient\")\n .AddResilienceHandler(\"retry\", rb =>\n rb.AddRetry(new() { MaxRetryAttempts = 3, Delay = TimeSpan.FromSeconds(2) }));\n<\/pre>\n\n\n\nIdempotency-Key<\/code>.
Even if the client loses connection mid-response, the next call retrieves the same result.<\/p>\n\n\n\n
\n\n\n\n⚙️Step 7 \u2014 Dockerize the API<\/h2>\n\n\n\n
Dockerfile<\/code> for container deployme<\/p>\n\n\n\nFROM mcr.microsoft.com\/dotnet\/sdk:9.0 AS build\nWORKDIR \/src\nCOPY . .\nRUN dotnet publish -c Release -o \/app\nFROM mcr.microsoft.com\/dotnet\/aspnet:9.0\nWORKDIR \/app\nCOPY --from=build \/app .\nEXPOSE 8080\nENTRYPOINT [\"dotnet\", \"OS.Tuto.IdempotentApi.dll\"]\n<\/pre>\n\n\n\n
docker build -t idempotent-api .\ndocker run -p 8080:8080 idempotent-api\n<\/pre>\n\n\n\n
⚙️Step 8 \u2014 Continuous Integration (GitHub Actions)<\/h2>\n\n\n\n
name: dotnet-build\non: [push, pull_request]\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - uses: actions\/checkout@v4\n - uses: actions\/setup-dotnet@v4\n with:\n dotnet-version: 9.0.x\n - run: dotnet restore\n - run: dotnet build -c Release\n<\/pre>\n\n\n\n
\n\n\n\nWhy This Approach Works<\/h2>\n\n\n\n
Feature<\/th> Description<\/th><\/tr><\/thead> Deterministic behavior<\/strong><\/td> Same request = same result<\/td><\/tr> Crash recovery<\/strong><\/td> If app restarts mid-request, replayed call returns saved response<\/td><\/tr> No double billing<\/strong><\/td> Perfect for payments and transactions<\/td><\/tr> Safe retry<\/strong><\/td> Integrates with Polly or API Gateway retries<\/td><\/tr> Scalable<\/strong><\/td> Replace IMemoryCache with Redis for distributed caching<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Going Distributed (Redis Option)<\/h2>\n\n\n\n
To make idempotency global, switch caching to Redis<\/strong>:<\/p>\n\n\n\ndotnet add package Microsoft.Extensions.Caching.StackExchangeRedis\n<\/pre>\n\n\n\n
builder.Services.AddStackExchangeRedisCache(o =>\n o.Configuration = \"localhost:6379\");\n<\/pre>\n\n\n\n
Common Pitfalls and Best Practices<\/h2>\n\n\n\n
Pitfall<\/th> Fix<\/th><\/tr><\/thead> Reusing the same key with different payload<\/td> Compare request hashes; reject with 409<\/td><\/tr> Very long TTL<\/td> Keep key records short (e.g., 24 h max)<\/td><\/tr> Missing key header<\/td> Return 400 Bad Request<\/code> early<\/td><\/tr>Non-deterministic logic<\/td> Avoid timestamps\/random outputs when replaying<\/td><\/tr> Memory cache only<\/td> Use distributed cache in multi-instance setups<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n When to Use Idempotency<\/h2>\n\n\n\n
Use Case<\/th> Why It Matters<\/th><\/tr><\/thead> Payment APIs<\/strong><\/td> Prevent double charges<\/td><\/tr> Order Checkout<\/strong><\/td> Avoid duplicate orders<\/td><\/tr> Webhook Consumers<\/strong><\/td> External systems often resend events<\/td><\/tr> IoT Devices<\/strong><\/td> Network drops cause resend<\/td><\/tr> Background jobs<\/strong><\/td> Retry logic needs determinism<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Client \u2500\u2500\u25ba API with Idempotency-Key\n \u2502\n \u251c\u2500 Key not found \u2192 Execute business logic\n \u2502 Store response in DB + cache\n \u2514\u2500 Key found \u2192 Return stored response\n<\/pre>\n\n\n\n
![\"\"](\"https:\/\/oussamasaidi.com\/wp-content\/uploads\/2025\/11\/oussama-saidi-tuto-net-core-rest-api-Idempotent-2-1.png\")
<\/figure>\n\n\n\n
\n\n\n\n Performance Notes<\/h2>\n\n\n\n
\n
\n\n\n\nTechnologies Used<\/h2>\n\n\n\n