By Frank Oelschlager
Idempotency. One of the key characteristics of REST, and yet so poorly understood (at least if one surveys the landscape of “RESTful” APIs available floating around out there). So what is idempotency exactly?
Essentially, it means that if one performs the same operation on a resource multiple times, the state of the resource will be exactly the same as after the first time the operation is performed. This includes both the data structure and the content.
For example (although physicists might disagree), the act of viewing a resource does not change it. Thus, the HTTP GET command, when applied to a REST API call, should be idempotent. Every single time the GET command is applied to a resource, the exact same resource is provided, and is not changed as a result of the operation. If the act of performing GET changes a resource (for example, the resource is updated with how many times it has been retrieved), idempotency is violated.
Certain commands, such as POST, have the potential (and are likely) to not be idempotent, so we generalize and say that POST is not idempotent. For example, say the POST command is applied to run a process on a resource that changes it based on some meta state. A good analog is a Ledger resource, composed of Ledger Entry resources. In an accrual based accounting system, specific Ledgers are “posted” to the General Ledger when they become manifest in the business (ie: a check clears). If one implemented the POST command on the Ledger resource to “post” the applicable entries to the GL, each time the resource is operated on, the resulting state will be different- the Ledger will contain a different set of Ledger Entries than before the operation. Further, in this case, it is likely that the Ledger Entry resources are themselves modified in a non-repeatable manner as a result of the operation being performed.