Home > Design Patterns > Idempotent Capability
Idempotent Capability

Idempotent Capability (Wilhelmsen, Pautasso)

How can a service capability safely accept multiple copies of the same message to handle communication failure?


Network and server hardware failure can lead to lost messages, resulting in cases where a service consumer receives no response to its request. Attempts to reissue the request message can lead to unpredictable or undesirable behavior when the service capability inadvertently receives multiple copies of the same request message.


Design service capabilities with idempotent logic that enables them to safely accept repeated message exchanges.


Idempotency guarantees that repeated invocations of a service capability are safe and will have no negative effect.

Idempotent capabilities are generally limited to read-only data retrieval and queries. For capabilities that do request changes to service state, their logic is generally based on "set", "put" or "delete" actions that have a post-condition that does not depend on the original state of the service.

The design of an idempotent capability can include the use of a unique identifier with each request so that repeated requests (with the same identifier value) that have already been processed will be discarded or ignored by the service capability, rather than being processed again.


The use of a unique identifier to define an idempotent capability requires session state to be reliably recorded by the service and preserved across server hardware failures. This can harm the scalability of the service, and may be further complicated if redundant service implementations are operating at different sites that experience network failures.

Not all service capabilities can be idempotent. Potentially unsafe capabilities include those that need to perform “increment”, “reverse” or “escalate” transition functions, where the post-execution condition is dependent upon the original state of the service.


Inventory, Composition, Service