Requests

Safe and idempotent methods

Understand the guarantees behind safe and idempotent methods so retries, links, caches, and automated clients behave predictably.

7 minute lesson

~~~

A safe method asks only to read information. GET, HEAD, and OPTIONS are safe. They should not request a change to server state.

An idempotent method has the same intended effect whether it is sent once or several times.

PUT is idempotent: sending the same complete replacement twice leaves the resource in the same state. DELETE is also idempotent: after the first deletion, repeating it does not delete another resource.

POST is usually not idempotent. Repeating a purchase request might create two orders.

This matters when a connection fails. A client can often retry an idempotent request safely. Retrying a non-idempotent request may need an idempotency key or application-specific protection.

Lesson completed