What is Idempotency?
Idempotency means that making the same API request multiple times has the same effect as making it once. In other words, no matter how many times you repeat the request, the result and the state of the server remain unchanged after the first successful call.
Why is Idempotency Important?
- Prevents duplicate actions: Avoids double bookings, double payments, or repeated changes.
- Makes retries safe: If a network error happens, your client can safely retry the request without worrying about causing unwanted side effects.
- Simplifies client logic: You don’t need complex checks to avoid duplicates—just retry if needed.
Appointment Booking Example
Imagine you want to book an appointment using a REST API. Here’s what can happen:
Without Idempotency
- You send a POST request to book an appointment.
- The network is slow, so your app resends the request, thinking the first one failed.
- The server processes both requests as new appointment.
- Result: You end up with two bookings for the same appointment and might be charged twice.
With Idempotency
- You send a POST request to book an appointment, including a unique Idempotency-Key in the header.
- If the request is retried (due to a timeout or error), the same Idempotency-Key is used.
- The server checks if it has already processed a request with that key:
- If yes, it returns the same booking confirmation as before.
- If no, it processes the booking and stores the key.
- Result: Only one booking is made, no matter how many times the request is sent.
What Happens Without Idempotency?
- Duplicate bookings/payments: Multiple charges or reservations for the same action.
- Inconsistent data: Server state becomes unreliable, leading to customer complaints and manual fixes.
- Harder error handling: Clients must implement complex logic to avoid duplicates, increasing bugs and maintenance.
Conclusion
- Idempotency is essential for safe, reliable APIs—especially for actions like booking, payments, or resource creation.
- Use a unique Idempotency-Key for each client request that should only be processed once.
- Always check for the key on the server before processing the request.
If you want to see a more advanced example (with Redis or a database for storing keys), let me know!