Designing robust and predictable APIs

Very interesting and useful observation:

Designing robust and predictable APIs with idempotency
by Brandur Leach from Stripe engineering

"Idempotent API: means that they can be called any number of times while guaranteeing that side effects only occur once."

"a few core principles to follow while designing your clients and APIs:

• Make sure that failures are handled consistently.
  Have clients retry operations against remote services.
  Not doing so could leave data in an inconsistent state that will lead to problems down the road.
  
• Make sure that failures are handled safely.
  Use idempotency and idempotency keys to allow clients to pass a unique value and retry requests as needed.
  
• Make sure that failures are handled responsibly.
  Use techniques like exponential backoff and random jitter.
  Be considerate of servers that may be stuck in a degraded state."