Master API idempotency vocabulary: idempotent HTTP methods, idempotency key header, safe vs. idempotent vs. neither, retry-safe operations — essential for professional API design discussions.
0 / 5 completed
1 / 5
The API designer says: 'The PUT request is idempotent but POST is not.' What does 'idempotent' mean in this context?
An idempotent operation produces the same result no matter how many times it is called. PUT is idempotent because sending the same PUT request repeatedly sets the resource to the same state each time. POST is not idempotent because each call typically creates a new resource.
2 / 5
The engineer says: 'We need to add an idempotency key header to the payment endpoint.' What is the purpose of an idempotency key?
An idempotency key is a unique value (typically a UUID) that the client includes in the request header. If the same key is sent again, the server recognises it as a duplicate and returns the cached result instead of processing the operation again — making retries safe.
3 / 5
A colleague explains: 'A safe HTTP method has no side effects.' Which of the following HTTP methods is both safe AND idempotent?
GET is both safe and idempotent. 'Safe' means the method does not modify the server state. 'Idempotent' means repeated calls have the same effect. GET merely retrieves data. PUT is idempotent but not safe (it modifies state). POST is neither safe nor idempotent.
4 / 5
The team discusses: 'These retry-safe operations need special handling.' What makes an operation 'retry-safe' in API design?
A retry-safe operation can be repeated — whether due to network timeout, client retry logic, or infrastructure failure — without causing unintended duplicate effects (such as double-charging a customer). Idempotency keys and idempotent HTTP methods are the main tools for achieving retry safety.
5 / 5
During a code review, the reviewer comments: 'PATCH is neither safe nor idempotent by default.' In what situation would a PATCH request NOT be idempotent?
PATCH is not guaranteed to be idempotent. If a PATCH applies a relative operation (for example, 'increment quantity by 1'), repeated calls will produce different results. If a PATCH sets an absolute value ('set quantity to 5'), it behaves idempotently. The key distinction is relative vs. absolute mutations.