Skip to content

Idempotency in HTTP Requests

Idempotency is a fundamental concept in [[RESTful API]] design, ensuring that making multiple identical requests has the same effect as making a single request.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md]

This property is crucial for network reliability, particularly when dealing with potential failures or retries.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md] If a client sends a request but does not receive a response (due to a network timeout, for example), idempotency guarantees that safely retrying the request will not cause unintended side effects, such as duplicate transactions or corrupted data.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md]

Idempotent HTTP methods

Not all HTTP methods are idempotent. The following methods are defined as idempotent:

  • GET: Retrieves a resource (one or multiple items).^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md] Sending a request once or multiple times yields the same result and does not alter the server state.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md]
  • PUT: Updates a resource using the complete data provided by the client.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md] Regardless of how many times the update is applied, the resource state remains consistent with the data provided in the request.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md]
  • DELETE: Removes a resource.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md] Once a resource is deleted, sending subsequent DELETE requests has no further effect; the result (the absence of the resource) remains the same.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md]
  • HEAD: Retrieves HTTP headers and status codes without the message body.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md] This method is idempotent and is often used to check resource availability or existence.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md]

Non-Idempotent HTTP methods

  • POST: Typically used to create a new resource.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md] Repeatedly submitting a POST request generally results in the creation of multiple resources or repeated processing, making it non-idempotent.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md]

Idempotency in Status Codes

The concept of idempotency also extends to specific HTTP status codes returned by the server, confirming whether an operation resulted in a state change:

  • 200 OK: Indicates the server successfully returned requested data and is an idempotent operation.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md]
  • 400 INVALID REQUEST: Signifies an error in the request that prevented data creation or modification; this is considered an idempotent operation.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md]
  • 404 NOT FOUND: Indicates the requested record does not exist and no operation occurred; this is idempotent.^[600-developer-principle-restful-rule.md, 600-developer__principle__restful-rule.md]
  • [[RESTful API]]
  • [[HTTP Verbs]]
  • [[Status Codes]]

Sources

^[600-developer-principle-restful-rule.md] ^[600-developer__principle__restful-rule.md]