API Development 101


Learn about idempotency and how idempotency keys prevent negative results from accidental duplicate requests.

What is idempotency?

An API call or operation is idempotent if it has the same result no matter how many times it is applied.

Square APIs require idempotency keys to protect against accidental duplicate calls when duplicate calls can have negative consequences (for example, charging a credit card twice). For example, suppose you make a successful Charge request, but your connection fails before you receive success confirmation. If you make the exact same request again, the endpoint knows it is a duplicate request and does NOT charge the card a second time. The result of your duplicate Charge requests is the same as if you had only made the request once.

Idempotency keys can be anything, but they need to be unique. Virtually all popular programming languages provide a function for generating unique strings.

Language Function
Ruby SecureRandom.uuid
PHP uniqid
Java UUID.randomUUID
Python uuid (Python 2, Python 3)
C# Guid.NewGuid
Node uuid
< Frontend vs. Backend
Pagination >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow