Understanding API Idempotency: A Practical Guide

Idempotency is a crucial concept in API design that ensures:

Making the same request multiple times produces the same result without side effects.

This means that if a client sends the same request twice (or more), the system should handle it gracefully without creating duplicate records or causing unintended consequences. Think of it like a light switch: pressing it multiple times doesn't create multiple lights--it just toggles the same light on or off.

Why Idempotency Matters

The Double-Charge Problem

Consider this common e-commerce scenario:

1. A user clicks "Pay $100" on a mobile app
2. The network connection is unstable
3. The user doesn't see a response
4. They click again
5. Result: The user gets charged $200 instead of $100

This is a real problem that affects user trust and can lead to:

• Customer support tickets
• Refund requests
• Loss of customer trust
• Potential legal issues

The Reload Problem

Another common issue occurs in booking systems:

1. User fills out a hotel booking form
2. Page generates a new bookingId = "booking_123"
3. User clicks "Confirm Booking" but the request fails
4. User reloads the page
5. A new bookingId = "booking_456" is generated
6. User clicks "Confirm Booking" again
7. Result: Two separate bookings are created for the same room and dates

Implementing Idempotency

Client-Side Implementation

The key is to generate and persist a stable ID that represents the user's intent. Here's a React hook that handles this:

// useIdempotentAction.ts import { useState, useEffect } from 'react'; import { v4 as uuidv4 } from 'uuid'; interface UseIdempotentActionProps { actionKey: string; // e.g., 'booking', 'payment', 'subscription' onSuccess?: () => void; } export function useIdempotentAction({ actionKey, onSuccess }: UseIdempotentActionProps) { const [actionId, setActionId] = useState<string>(''); const storageKey = `${actionKey}-id`; useEffect(() => { // Try to retrieve existing action ID const saved = localStorage.getItem(storageKey); if (saved) { setActionId(saved); } else { // Generate new ID if none exists const newId = uuidv4(); localStorage.setItem(storageKey, newId); setActionId(newId); } }, [storageKey]); const clearActionId = () => { localStorage.removeItem(storageKey); setActionId(''); onSuccess?.(); }; return { actionId, clearActionId }; } 

Usage in a booking component:

// BookingForm.tsx function BookingForm() { const { actionId, clearActionId } = useIdempotentAction({ actionKey: 'booking', onSuccess: () => { // Show success message // Redirect to confirmation page } }); const handleSubmit = async (formData: BookingFormData) => { try { const response = await fetch('/api/bookings', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Idempotency-Key': actionId }, body: JSON.stringify({ ...formData, idempotencyKey: actionId }) }); if (response.ok) { clearActionId(); } } catch (error) { // Handle error } }; return ( <form onSubmit={handleSubmit}> </form> ); } 

Why Client-Side ID Generation?

The client is the best place to generate the ID because:

1. Intent Tracking: It knows the exact moment of user intent
2. State Persistence: It can persist the ID across page reloads
3. Retry Management: It can track retry attempts
4. Industry Standard: It follows the pattern used by industry leaders like Stripe and PayPal

Practical Implementation with Supabase

Client-Side Code

// api/bookings.ts interface BookingRequest { roomId: string; checkIn: string; checkOut: string; guestInfo: { name: string; email: string; }; } async function createBooking(bookingData: BookingRequest, idempotencyKey: string) { const response = await fetch('/api/bookings', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey }, body: JSON.stringify({ ...bookingData, idempotencyKey }) }); if (!response.ok) { throw new Error('Booking failed'); } return response.json(); } 

Server-Side Code

// pages/api/bookings.ts import { createClient } from '@supabase/supabase-js'; const supabase = createClient( process.env.NEXT_PUBLIC_SUPABASE_URL!, process.env.SUPABASE_SERVICE_KEY! ); export default async function handler(req: NextApiRequest, res: NextApiResponse) { if (req.method !== 'POST') { return res.status(405).json({ error: 'Method not allowed' }); } const { idempotencyKey, ...bookingData } = req.body; try { // First, check if we've already processed this request const { data: existingBooking } = await supabase .from('bookings') .select('*') .eq('idempotency_key', idempotencyKey) .single(); if (existingBooking) { // Return the existing booking return res.status(200).json(existingBooking); } // Process new booking const { data, error } = await supabase .from('bookings') .insert({ ...bookingData, idempotency_key: idempotencyKey, status: 'confirmed', created_at: new Date().toISOString() }) .select() .single(); if (error) { throw error; } return res.status(201).json(data); } catch (error) { console.error('Booking error:', error); return res.status(500).json({ error: 'Booking failed' }); } } 

Best Practices for Idempotency

1. Generate Stable IDs

   • Use UUIDs (v4) for uniqueness
   • Include a prefix for different action types (e.g., booking_, payment_)
   • Store them in localStorage, cookies, or session storage
   • Clear them after confirmed success

2. Handle Edge Cases

   • Network failures and timeouts
   • Page reloads and browser crashes
   • Multiple clicks and rapid retries
   • Concurrent requests

3. Server-Side Considerations

   • Use database constraints and unique indexes
   • Implement proper error handling and logging
   • Set appropriate timeouts for idempotency keys
   • Consider using a distributed cache (Redis) for high-traffic systems

4. Security Considerations

   • Validate idempotency keys
   • Set expiration times for keys
   • Implement rate limiting
   • Log suspicious patterns

Summary

Idempotency is not about preventing duplicate requests--it's about handling them gracefully. A well-designed system should:

• Accept the same request multiple times
• Process it only once
• Return the same result each time
• Maintain data consistency
• Handle errors gracefully

Remember:

Your job isn't to block duplicates.

Your job is to make sure they don't hurt anyone.

By implementing proper idempotency, you create a more resilient system that can handle real-world scenarios like:

• Poor network conditions
• User impatience
• Browser refreshes
• Mobile app backgrounding
• Service interruptions

This leads to:

• Better user experience
• Fewer support tickets
• More reliable systems
• Happier customers