Question 1

What is idempotency and why does it matter for APIs?

Accepted Answer

An operation is idempotent when performing it more than once has the same effect as performing it once. Setting a value to ten is idempotent; adding ten is not. The property matters because networks fail in a specific, awkward way: a client can send a request, never receive the response, and have no way to know whether the server processed it.

Without idempotency the client faces an unpleasant choice. Retrying risks doing the work twice, which for a payment or an order is a real problem. Not retrying risks losing the operation entirely. Idempotency removes the dilemma, because retrying is simply safe.

Several HTTP methods are idempotent by definition. Reading, replacing and deleting a specific resource all have the property naturally, since repeating them lands on the same final state. Creating a resource by posting to a collection does not, because each call is meant to make a new one.

The standard solution for the create case is an idempotency key. The client generates a unique value per logical operation and sends it as a header. The server records the key alongside the result, and if the same key arrives again it returns the stored response instead of doing the work a second time. Retries then converge on one outcome no matter how often the request is repeated.

Getting this right requires a few details. The key must be stored atomically with the effect, or a crash between the two reopens the same hole. It needs an expiry, or the store grows forever. And the same key arriving with a different payload should be rejected rather than silently served the old response, since that indicates a client bug.

Any API touching money or sending messages should treat this as a requirement rather than a refinement.

Question 2

What makes a good API design?

Accepted Answer

Predictability above cleverness — a good API is one where a developer can guess correctly what something is called and how it behaves, because they will guess far more often than they will read the

Question 3

What is the difference between HTTP 401 and 403?

Accepted Answer

The short version is that 401 concerns identity and 403 concerns permission. A 401 means the request was not authenticated: no credentials were supplied, or the ones supplied were not valid. A 403

Question 4

What is a webhook?

Accepted Answer

An HTTP request sent by a service to you when something happens — the inverse of an API call, and the reason it is sometimes described as a reverse API or a push notification for servers. The problem

Question 5

What is API versioning, and how do you avoid breaking clients?

Accepted Answer

Managing change in an interface other people depend on — where the governing constraint is that once an API is published, you no longer control when consumers update, and in many cases they never

Question 6

What is eventual consistency?

Accepted Answer

Eventual consistency is a guarantee that, if no new updates are made, all replicas of a piece of data will eventually converge on the same value. It does not guarantee when, and it permits reads that

Question 7

Why is cache invalidation considered hard?

Accepted Answer

The famous quip from Phil Karlton is that there are two hard things in computer science: cache invalidation and naming things. The joke endures because the problem is genuinely difficult, and the

Related Questions