Membangun API Idempotent: Solusi Elegan Menangani Double Request

Pendahuluan

Kita pasti pernah ketemu bug konyol ini: user koneksinya lemot, tombol submit diklik berkali-kali, dan boom! Data masuk ke database berlipat ganda.

Biasanya, frontend developer yang disuruh nambal pakai debouncing atau nge-disable tombol. Padahal, masalah utamanya ada di desain API kita.

Di sinilah konsep Idempotent API menyelamatkan hidup kita. Topik ini krusial banget, terutama kalau kita bikin sistem transaksional yang pantang punya data ganda.

Konsep Dasar / Gambaran Arsitektur

Secara sederhana, idempotent berarti: mau kamu memanggil API sekali atau seribu kali, hasil akhirnya di database tetap sama.

Bawaan HTTP method seperti GET, PUT, PATCH, dan DELETE itu sejatinya sudah idempotent. Yang sering jadi biang kerok adalah POST karena tugasnya meng-create data baru.

Bayangkan kamu pesan kopi di kafe. Kasir memberimu struk dengan nomor antrean pesanan (Idempotency Key atau Unique ID).

Kalau kamu maju lagi ke kasir dan memberikan struk yang sama, kasir tahu itu pesanan yang sudah diproses, bukan pesanan baru. Backend kita harusnya kerja seperti kasir ini.

Step-by-Step Implementasi

Untuk membuat endpoint POST menjadi idempotent, kita butuh sebuah unique identifier dari client, misalnya SKU barang atau sebuah UUID khusus.

Alih-alih langsung melakukan INSERT, kita cek dulu apakah identifier tersebut sudah ada di sistem. Berikut contoh implementasinya di controller Laravel:

CODE

public function store(Request $request)
{
    // Menggunakan updateOrCreate untuk memastikan idempotency
    // Berdasarkan 'sku' yang sifatnya unik per produk
    $product = Product::updateOrCreate(
        ['sku' => $request->sku], // Kondisi pencarian (Idempotency Key)
        ['name' => $request->name, 'price' => $request->price] // Data yang diupdate/insert
    );

    return response()->json([
        'message' => 'Product processed successfully',
        'data' => $product
    ], 200);
}

Jika kamu butuh level idempotency yang lebih ketat (misal untuk API Payment), kamu bisa menyimpan Idempotency-Key di Redis agar lebih cepat divalidasi.

Berikut contoh konfigurasi docker-compose.yml sederhana untuk menyalakan Redis di environment lokalmu:

CODE

version: "3.8"
services:
  redis:
    image: redis:alpine
    container_name: local-redis
    ports:
      - "6379:6379"
    restart: unless-stopped

Studi Kasus / Masalah Umum

Kesalahan Umum: Seringkali developer membuat validasi unik di database (misal kolom SKU di-set UNIQUE), lalu membiarkan aplikasi crash atau melempar HTTP 500 saat terjadi duplikasi.

Kenapa ini buruk? User yang tidak sengaja double-click akan melihat pesan Error di layar, padahal request pertamanya sukses masuk ke database. Mereka jadi bingung.

Solusi Praktis: Jangan kembalikan error. Tangkap exception-nya atau gunakan teknik Upsert (updateOrCreate) seperti kode di atas. Kembalikan HTTP 200 OK dengan data yang ada agar flow di client-side tetap mulus.

Kesimpulan

Method GET, PUT, PATCH, dan DELETE secara natural sudah idempotent.
Endpoint POST butuh penanganan khusus menggunakan Unique ID (seperti SKU) atau Idempotency Header.
Hindari melempar error membingungkan saat double request terjadi; handle secara elegan dengan upsert atau abaikan operasi duplikatnya.

Tanggung jawab integritas data itu wajib ada di backend. Menggeser beban validasi logika ini ke sisi server bikin kode frontend saya jadi jauh lebih bersih dan tenang saat dide-deploy.