What is Idempotency?: Practical Design Points for APIs That Don't Break

Differences between idempotency, safety, and caching.

By separating the concepts of "idempotency," "safety," and "cacheability," which are often confused in the context of HTTP, method selection and API specification explanations become much clearer.
Idempotency refers to the property that the final resource state does not change even if retransmissions or multiple transmissions occur, safety refers to not changing the server state in the first place, and cacheability refers to whether the same result can be reused, so each has a different purpose.

In practice, being able to distinguish between these three types makes it easier to explain things like "GET is secure and can be retransmitted, but caching is conditional" and "POST is not idempotent, but there are cases where it should be made idempotent." In particular, idempotency is important to incorporate into the design as a contract that absorbs network uncertainty.

▼I want to know more about the API
⇒ API｜Glossary

Back to Top

Definition of idempotency

Idempotency is the property that even if the same request is executed multiple times, the state of the resource retained as a result will be the same as when it was executed only once. This is a different concept from the response being exactly the same each time.
For example, if sending the same expression multiple times using PUT results in a state that converges to the same state, then it is idempotent. However, if each resend increases the number of records or results in duplicate billing, then it is not idempotent. Clearly defining this difference in the specifications is a prerequisite for retry design.

Back to Top

Idempotency and design intent of different HTTP methods

HTTP methods are not merely functional classifications but contracts defining "what the operation means," and aligning idempotent expectations greatly simplifies client-side error handling.

GET: Assumes safety and idempotency.

GET requests are designed to be read-only and are thoroughly secure to ensure safe retransmission and caching. However, if state changes such as page view updates or marking as read are included, they can be unintentionally executed by caches and crawlers, potentially polluting the data. Therefore, state changes need to be separated to a different endpoint.

PUT: Full resource update and idempotency

PUT is treated as a complete replacement of a resource, and idempotency is ensured by designing it to converge to the same state no matter how many times the same content is sent. However, in practice, it is important to combine it with conditional updates using ETag or If-Match to prevent overwriting problems due to simultaneous updates.

DELETE: Convergence to the delete state

DELETE is idempotent because it converges to a deleted state. While there is design flexibility in deciding whether to use a 204 or 404 response for subsequent requests, the important thing is to have a consistent contract that simplifies client branching.

PATCH: Condition for making partial updates idempotent

PATCH can be idempotent or idempotent depending on its design. It can be made idempotent by shifting the operation from "applying the difference" to "setting to a target state." However, incremental updates like +1 tend to be idempotent because the state changes with each retransmission, so it is effective to design it to be separated into a separate resource as a command when necessary.

POST: Non-idempotent but requires idempotency.

POST requests are inherently non-idempotent, meaning multiple resources are created with each resend of the same request. However, in processes where duplication is critical, such as order placement and payment processing, retries are essential. Therefore, it is crucial in practice to define which POST requests should be idempotent as a requirement.

Back to Top

Why is idempotence essential in practical applications?

Idempotency is not merely a convention in API design; it's a design philosophy for controlling the costs of abnormal situations, based on the premise that "communication will inevitably fail." Especially now that cloud environments and microservice configurations are commonplace, the stability of a system depends more on "how simply it behaves in the event of failure" than on the elegance of its normal operation.

The assumption is that communication will always fail.

In a distributed environment, ambiguous failures such as no response being received or a timeout occurring even though the processing itself is completed are unavoidable, and it is not practical to design the system to treat a client resending in this situation as an exception.

If the system does not assume that the same request will be received multiple times, additional design elements such as status query APIs to inquire about success or failure, manual confirmation flows, and post-registration corrections for duplicate entries will be required, resulting in increased complexity in both implementation and operation. However, with idempotency, the client can simply resend the request, significantly simplifying the overall system behavior.

Design to minimize abnormal system costs

The essence of idempotency lies in the fact that "resending does not break the data," thereby reducing branching in abnormal situations and avoiding the need to bring decision-making logic to the client side.

With non-idempotent APIs, it becomes necessary to check each step to see if resending is acceptable, if it has already succeeded, or if it has only been partially processed. However, with idempotent APIs, a simple strategy of "just resend" is possible, and abnormal cases do not need to be treated specially, resulting in the most cost-effective design.

Back to Top

Why idempotence becomes more important in an iPaaS environment

Even if a lack of idempotency is not apparent in a standalone API, when multiple systems are linked via iPaaS, retries, parallel execution, and re-execution are structurally incorporated, so the presence or absence of idempotency directly impacts the failure rate and the difficulty of recovery.

▼I want to know more about iPaaS
⇒ iPaaS | Glossary

Retrying is a "prerequisite," not an "exception."

In iPaaS, it is common to configure automatic retries for temporary errors or network fluctuations in external APIs, which is a correct design for increasing availability. However, if the linked API is not idempotent, orders may be registered twice or inventory may be deducted twice with each resend, raising questions about the soundness of the API contract even before considering the flow design.

In other words, iPaaS is not something that creates problems, but rather a catalyst that brings to light the inherent weaknesses of non-idempotent designs, and the stability of the collaboration platform strongly depends on the idempotency of the connected APIs.

Operational Reality: Re-execution and Partial Recovery

Operational reprocessing, such as batch reruns, restarts from intermediate nodes, and partial recoveries, is unavoidable. If the design amplifies side effects each time, it leads to a vicious cycle where disaster recovery creates new problems.
Whether a flow can be safely re-executed depends on whether the individual APIs and database operations are designed to be idempotent; a design that allows for re-execution is also a "recoverable design."

Parallel execution and conflicts

While iPaaS makes it easy to configure scaling out and parallel processing, if simultaneous operations on the same data occur, record duplication and conflicting updates will manifest as real-world problems unless idempotency and uniqueness constraints are properly designed.

The role of idempotent keys and unique constraints

Idempotent and natural key constraints are not merely implementation techniques; they are structural safeguards based on the premise of distributed collaboration. By physically guaranteeing that "multiple attempts will converge to a single attempt," they make retries and parallel execution safer.

Back to Top

Implementation patterns for idempotency of POST requests and iPaaS integration

POST is inherently a non-idempotent method where multiple resources can be generated by resending the same request. However, in processes where "duplication is critical," such as order registration, payment processing, and data integration with external SaaS, retries are assumed. Therefore, in practice, it is necessary to define the unit at which POST requests should be idempotent as a requirement.
Especially in iPaaS environments like HULFT Square, it is common to configure retries and re-executions for external API calls, and the stability of the flow strongly depends on the idempotent design of the connected API. Therefore, idempotency of POST requests is not a "design option" but a "prerequisite that affects the quality of integration."

Idempotency-Key method

The method of using idempotent keys in requests and returning the same result without re-executing internal processing when the same key is resent enables safe automatic retransmission when combined with HULFT Square 's retry control. However, if the key retention period and the response policy in case of collisions are not determined at the design stage, it can conversely create ambiguity.

Structural prevention through unique constraints

Rather than relying on application-level "existence checks," a design that physically prevents duplicate entries using database unique constraints and natural keys is the most reliable defense in a distributed environment and possesses robustness that can withstand multiple access attempts from iPaaS.

Client-generated ID method

The design, which generates a UUID on the client side and converges on retransmissions using the same ID, makes it easier to maintain consistency when re-executing via iPaaS or restarting the flow, and is a particularly effective pattern for external SaaS integrations.

Checkpoints when designing flows based on idempotency in HULFT Square

When designing API integrations in HULFT Square, you need to build the structure based on the premise of "not breaking even if resent" rather than "not failing."

The first thing to check is whether the linked API is idempotent. If you enable retries while POST requests are not idempotent, duplicate registrations and double processing will become apparent.

Next, it's crucial to clarify the responsibilities of retries. Unless we define the extent to which HTTP-level automatic retries, node-level retrying, and whole-flow retrying are acceptable side effects, recovery efforts will create new inconsistencies.

Furthermore, it is important that a unique key is determined at the entry point of the flow. Intermediate numbering makes it difficult to converge during re-execution, so a design that ensures uniqueness at the entry point is more stable in an iPaaS environment.

HULFT Square offers flexible configuration options for retries and parallel execution, but this flexibility is only truly beneficial when the API is designed to be idempotent.
iPaaS doesn't create problems; it's a layer that makes the weaknesses of non-idempotent designs visible.

Back to Top

Typical patterns and countermeasures for breaking idempotency

Idempotency can easily be broken down in the details of the design, so it is important to understand typical failure patterns in advance.

• Duplicate creation due to automatic numbering → Prevent with idempotent keys or unique constraints.
• Incremental updates (e.g., +1) → Controlled by updating to a target state or by creating commands.
• Multiple executions of asynchronous processes → Make the job creation itself idempotent.

Back to Top

Error handling and testing perspectives

Idempotency must be designed to include contracts in both success and failure scenarios. It is crucial to have specifications that allow clients to immediately determine whether resending is permissible, such as rejecting different content with the same key using a 409 error.
The tests must intentionally introduce multiple submissions of the same request and parallel execution, verifying that the final state converges to a single execution, and even verifying the number of times external side effects are executed.

Back to Top

summary

Idempotency is a simple property that states "the final state does not change even if the same request is resent," yet in distributed environments, it is a core design requirement for absorbing communication uncertainty and stabilizing behavior in the event of failures.
First, by specifically defining three points—"which operations can be resent," "at what unit should uniqueness be guaranteed," and "how to return a response in case of failure"—and by clearly documenting idempotency as a specification, you can take a step closer to creating a robust and easy-to-operate API.

Back to Top

The person who wrote the article

Affiliation: Marketing Department

Yoko Tsushima

After joining Appresso (now Saison Technology), he worked as a technical sales representative, in charge of technical sales, training, and technical events. After leaving the company to return to his hometown, he rejoined the company in April 2023 under the remote work system. After gaining experience in the product planning department, he is currently in charge of creating digital content in the marketing department.
(Affiliations are as of the time of publication)

Recommended Content

Related Content