百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
I

IdempotentAPI

> 编程语言
开源

一个 .NET 库,它使用 ASP 处理 HTTP 写操作(POST 和 PATCH),这些操作只能对给定的请求数据和 idempotency 密钥进行一次操作。

329 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

一个 .NET 库,它使用 ASP 处理 HTTP 写操作(POST 和 PATCH),这些操作只能对给定的请求数据和 idempotency 密钥进行一次操作。

Idempotent API (v2.6.0)

Understanding Idempotency

A distributed system consists of multiple components located on different networked computers, which communicate and coordinate their actions by passing messages to one another from any system. For example, I am sure that you have heard of the microservices architecture, which is a kind of distributed system.

Creating Web APIs for distributed systems is challenging because of distribution pitfalls such as process failures, communication failures, asynchrony, and concurrency. One common requirement and challenge when building fault-tolerant distributed applications is the need to be idempotent.

  • In mathematics and computer science, an operation is idempotent when applied multiple times without changing the result beyond the initial application.
  • Fault-tolerant applications can continue operating despite the system, hardware, and network faults of one or more components, ensuring high availability and business continuity for critical applications or systems.

Idempotence in Web APIs ensures that the API works correctly (as designed) even when consumers (clients) send the same request multiple times. For example, this case can happen when the API failed to generate the response (due to process failures, temporary downtime, etc.) or because the response was generated but could not be transferred (network issues).

Imagine a scenario in which the user clicks a “Pay” button to make a purchase. For unknown reasons, the user receives an error, but the payment was completed. If the user clicks the “Pay” button again or the request is re-sent by a retry library, we would result in two payments! Using idempotency, the user will get a successful message (e.g., on the second try), but only one charge would be performed.

Creating Idempotent Web APIs is the first step before using a resilient and transient-fault-handling library, such as Polly. The Polly .NET library allows developers to express policies such as Retry, Circuit Breaker, Timeout, Bulkhead Isolation, and Fallback in a fluent and thread-safe manner.

The IdempotentAPI library provides an easy way to develop idempotent Web APIs. In the following sections, we will see the idempotency in the different HTTP methods, how the IdempotentAPI library works, its code, and finally, how to use the IdempotentAPI NuGet packages.

Idempotency in HTTP (Web)

HTTP defines a set of request methods (HTTP verbs: GET, POST, PUT, PATCH, etc.) to indicate the desired action to be performed for a given resource. An idempotent HTTP method can be called many times without resulting in different outcomes. Safe methods are HTTP methods that do not modify the resources. In Table 1, we can see details about which HTTP methods are idempotent or/and safe.

Table 1. - Idempotent or/and Safe HTTP methods (verbs).

HTTP Method Idempotent Safe Description
GET Yes Yes Safe HTTP methods do not modify resources. Thus, multiple calls with this method will always return the same response.
OPTIONS Yes Yes Same as the previous HTTP method.
HEAD Yes Yes Same as the previous HTTP method.
PUT Yes No The PUT HTTP method is idempotent because calling this HTTP method multiple times (with the same request data) will update the same resource and not change the outcome.
DELETE Yes No The DELETE HTTP method is idempotent because calling this HTTP method multiple times will only delete the resource once. Thus, numerous calls of the DELETE HTTP method will not change the outcome.
POST No No Calling the POST method multiple times can have different results and will create multiple resources. For that reason, the POST method is not idempotent.
PATCH No No The PATCH method can be idempotent depending on the implementation, but it isn’t required to be. For that reason, the PATCH method is not idempotent.

Idempotent Web Consumer

The creation of an idempotent consumer is an essential factor in HTTP idempotency. The API server would need a way to recognize subsequent retries of the same request. Commonly, the consumer generates a unique value, called idempotency-key, which the API server uses for that purpose. In addition, when building an idempotent consumer, it is recommended to:

  • Use "V4 UUIDs" for the creation of the idempotency unique keys (e.g. “07cd2d27-e0dc-466f-8193-28453e9c3023”).
  • Use techniques like the exponential backoff and random jitter, i.e., including an exponential and random delay between continuous requests.

The IdempotentAPI Library

The IdempotentAPI is an open-source NuGet library, which implements an ASP.NET Core attribute (filter) to handle the HTTP write operations (POST and PATCH) that can affect only once for the given request data and idempotency-key.

How IdempotentAPI Works

The API consumer (e.g., a Front-End website) sends a request including an Idempotency-Key header unique identifier (default name: IdempotencyKey). The API server checks if that unique identifier has been used previously for that request and either returns the cached response (without further execution) or save-cache the response along with the unique identifier. The cached response includes the HTTP status code, the response body, and headers.

Storing data is necessary for idempotency, but if the data are not expired after a certain period, it will include unneeded complexity in data storage, security, and scaling. Therefore, the data should have a retention period that makes sense for your problem domain.

The IdempotentAPI library performs additional validation of the request’s hash-key to ensure that the cached response is returned for the same combination of Idempotency-Key and Request to prevent accidental misuse.

The following figure shows a simplified example of the IdempotentAPI library flow for two exact POST requests. As shown, the IdempotentAPI library includes two additional steps, one before the controller’s execution and one after constructing the controller’s response.

Figure 1. - A simplified example of the IdempotentAPI flow for two exact POST requests.

✔ Features

  • ⭐ Simple: Support idempotency in your APIs easily with simple steps 1️⃣2️⃣3️⃣.
  • Validations: Performs validation of the request’s hash-key to ensure that the cached response is returned for the same combination of Idempotency-Key and Request to prevent accidental misuse.
  • Use it anywhere!: IdempotentAPI targets .NET Standard 2.0. So, we can use it in any compatible .NET implementation (.NET Framework, .NET Core, etc.). Click here to see the minimum .NET implementation versions that support each .NET Standard version.
  • ⚙ Configurable: Customize the idempotency in your needs.
    • Configuration Options (see below for more details)
    • Logging Level configuration
    • ✳ NEW ✳ - Configure the Newtonsoft SerializerSettings based on your needs.
  • Caching Implementation based on your needs.
    • DistributedCache: A build-in caching that is based on the standard IDistributedCache interface.
    • FusionCache: A high performance and robust cache with an optional distributed 2nd layer and some advanced features.
    • ... or you could use your own implementation
  • Support idempotency in a Cluster Environment (i.e., a group of multiple server instances) using Distributed Locks.
    • samcook/RedLock.net: Supports the Redis Redlock algorithm.
    • madelson/DistributedLock: Supports multiple technologies such as Redis, SqlServer, Postgres and many more.
  • Powerful: Can be used in high-load scenarios.
  • Supports Minimal APIs.
  • ✳ NEW ✳ - Support FastEndpoints, a developer-friendly alternative to Minimal APIs and MVC.

Main NuGet Packages

Package Name Description Release
IdempotentAPI The implementation of the IdempotentAPI library.
IdempotentAPI.AccessCache The access cache implementation of the IdempotentAPI project.
IdempotentAPI.MinimalAPI The implementation to support IdempotentAPI in Minimal APIs.

Caching NuGet Packages

Package Name Description Release
IdempotentAPI.Cache.Abstractions The cache definition of the IdempotentAPI project.
IdempotentAPI.Cache.DistributedCache The default caching implementation, based on the standard IDistributedCache interface.
IdempotentAPI.Cache.FusionCache Supports caching via the FusionCache third-party library.

Distributed Locking NuGet Packages

| Package Name | Description | Release | | -------------------------------------

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

C#

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言