The Amazon EC2 API includes functions which create resources such as instances, disk volumes and snapshots, IP addresses, and key pairs.
Some of these functions create the resources in a synchronous fashion and you can determine the success or failure of the request by examining the value returned by the call.
Other functions work in an asynchronous fashion. Making the call initiates an action that may take a fairly long time (seconds or minutes) to complete. When the call returns you cannot know if the request has succeeded or not. Timeouts and connection errors can further muddy the water; you don't want to unnecessarily retry a request if there's an associated cost for the resource. You don't want to create two EC2 instances when you only needed one.
To provide you with better control in this situation, we've just a released a somewhat esoteric (yet very useful) feature called idempotent instance creation.
Performing an idempotent operation more than once yields the same result as applying it just once. Washing your dog is idempotent (you always end up with a clean dog); feeding your dog is not (your dog will get fat).
The EC2 RunInstances function now supports idempotency. If you are launching EC2 instances as part of a higher level process, this feature should help you to build management and control applications that are more robust.
To call RunInstances in an idempotent fashion, you need to create a client token. A client token is a case-sensitive string of up to 64 ASCII characters. You should use a unique client token for each new instance.
Once you have a properly formed client token, you simply pass it along as an additional parameter to RunInstances. The function will ignore the second and subsequent requests that have the same token. You must use the same set of parameters each time you call the function. If you don't you will get an IdempotentParameterMismatch error.
Read more about idempotency in the newest version of the EC2 Developer Guide.
Next feature: Filtering.