Idempotency Key pada API: Mencegah Transaksi Ganda saat Retry

Pernahkah aplikasi pembayaran menampilkan status tidak jelas karena koneksi terputus tepat setelah tombol bayar ditekan? Pengguna mungkin menekan tombol lagi, sementara permintaan pertama ternyata sudah diproses. Tanpa perlindungan yang tepat, sistem berisiko membuat dua transaksi untuk satu tindakan. Masalah serupa dapat terjadi pada pemesanan tiket, pembuatan pesanan, dan operasi API lain yang mengubah data.

Salah satu pola untuk mengatasi masalah ini adalah idempotency key. Mekanisme ini memungkinkan klien mengirim ulang permintaan tanpa membuat efek bisnis baru setiap kali permintaan diulang. Berikut cara menerapkannya tanpa menganggapnya sebagai pengganti validasi dan kontrol keamanan API.

Apa Itu Idempotency Key?

Idempotency key adalah nilai unik yang disertakan klien pada permintaan API untuk menandai satu operasi logis. Server menyimpan kunci bersama konteks permintaan dan hasil pemrosesannya. Jika permintaan datang kembali dengan kunci yang sama, server dapat mengembalikan hasil sebelumnya alih-alih menjalankan operasi sekali lagi.

Misalnya, aplikasi membuat pesanan dengan kunci order-7f2c.... Jika koneksi terputus setelah server menyimpan pesanan, klien mengulang permintaan dengan kunci tersebut. Server mengenali bahwa operasi sudah diproses dan tidak membuat pesanan kedua. Kunci dibuat untuk satu tindakan, bukan dipakai terus-menerus untuk semua permintaan pengguna.

Mengapa Retry Bisa Menimbulkan Duplikasi?

Jaringan tidak selalu memberi klien jawaban yang jelas tentang hasil operasi. Server mungkin sudah menyimpan perubahan, tetapi respons hilang karena koneksi terputus, gateway mengalami timeout, atau aplikasi ditutup sebelum menerima jawaban. Dari sudut pandang klien, permintaan tampak gagal meskipun efeknya sudah terjadi.

Retry penting untuk ketahanan layanan, tetapi mengulang operasi yang tidak aman terhadap pengulangan bisa menimbulkan tagihan ganda, stok berkurang dua kali, tiket terbit dua kali, atau notifikasi berulang. Idempotency key menghubungkan percobaan-percobaan itu dengan satu operasi. Ini berbeda dari menonaktifkan tombol sementara karena perangkat atau sistem lain masih dapat mengirim permintaan berulang.

Alur Kerja yang Disarankan

1. Klien membuat kunci. Buat nilai acak yang cukup kuat untuk setiap tindakan logis, misalnya saat pengguna mengonfirmasi pembayaran. Simpan kunci selama proses retry agar percobaan berikutnya memakai nilai yang sama.
2. Server memeriksa kunci. Cari kunci dalam ruang lingkup yang sesuai, seperti akun pemilik dan jenis endpoint. Kunci bukan pengganti autentikasi dan otorisasi.
3. Validasi isi permintaan. Ikat kunci pada sidik jari permintaan, misalnya metode, endpoint, akun, dan parameter bisnis penting. Jika kunci sama dipakai dengan isi berbeda, tolak permintaan.
4. Catat status pemrosesan. Gunakan status seperti sedang diproses, berhasil, atau gagal yang boleh dicoba ulang. Penyimpanan kunci dan perubahan bisnis harus konsisten agar dua permintaan bersamaan tidak lolos pemeriksaan.
5. Simpan dan ulangi hasil. Setelah operasi selesai, simpan hasil yang perlu dikembalikan. Permintaan ulang dengan kunci dan isi yang cocok menerima hasil yang sama atau respons setara yang terdokumentasi.

Merancang Penyimpanan dan Masa Berlaku

Catatan idempotensi perlu memiliki batas masa simpan sesuai pola retry dan risiko bisnis. Masa simpan terlalu pendek dapat membuat permintaan lama diproses kembali setelah catatan kedaluwarsa; masa simpan terlalu panjang menambah kebutuhan penyimpanan. Dokumentasikan berapa lama klien boleh mengulang operasi.

Gunakan batasan unik di basis data untuk ruang lingkup kunci yang dipilih. Ini penting saat dua permintaan dengan kunci identik tiba hampir bersamaan. Pemeriksaan aplikasi saja tidak cukup karena kedua proses dapat membaca bahwa kunci belum ada sebelum salah satunya menyimpan catatan. Tangani konflik unik sebagai kondisi yang diharapkan.

Untuk operasi yang memanggil sistem eksternal, gunakan kunci idempotensi yang didukung penyedia jika tersedia. Jika tidak, sediakan rekonsiliasi dan penanganan status tidak pasti agar timeout tidak otomatis dianggap sebagai bukti kegagalan.

Respons API dan Penanganan Kesalahan

Tetapkan perilaku konsisten untuk setiap keadaan. Kunci yang sedang diproses dapat menghasilkan respons konflik atau status sementara dengan petunjuk retry yang jelas. Kunci yang selesai mengembalikan hasil tersimpan. Kunci yang dipakai dengan payload berbeda menghasilkan kesalahan validasi. Jangan menyertakan detail internal atau data sensitif dalam respons tersimpan.

Klien memerlukan aturan retry yang wajar, seperti jeda bertahap dengan variasi acak dan batas jumlah percobaan. Retry tanpa batas dapat memperparah gangguan layanan. Untuk perlindungan endpoint secara menyeluruh, baca juga panduan keamanan API di Nazuaf.com, termasuk autentikasi, otorisasi, dan validasi masukan.

Keamanan dan Privasi Kunci

Idempotency key bukan kata sandi dan bukan bukti hak akses. Kunci yang bocor dapat mengungkap hasil operasi jika server tidak memeriksa identitas pemanggil. Gunakan nilai acak yang sulit ditebak, batasi akses catatan berdasarkan akun atau tenant, dan jangan memasukkan data pribadi ke dalam kunci.

Perhatikan log dan analitik. Catat pengenal yang diperlukan untuk penelusuran, tetapi hindari menyimpan payload sensitif demi debugging. Tetapkan batas ukuran kunci, validasi formatnya, dan pantau lonjakan penggunaan yang mungkin menunjukkan bug klien atau penyalahgunaan API.

Cara Menguji Implementasi

• Kirim permintaan yang sama dua kali dengan kunci sama dan pastikan hanya ada satu efek bisnis.
• Putuskan koneksi setelah server memproses operasi, lalu lakukan retry dengan kunci yang sama.
• Kirim dua permintaan bersamaan dengan kunci identik untuk menguji perlombaan proses.
• Gunakan kunci sama dengan payload berbeda dan pastikan server menolak konflik.
• Uji retry setelah masa simpan berakhir sesuai dokumentasi.
• Pastikan tenant lain tidak dapat membaca hasil milik pemilik kunci berbeda.

Kesimpulan

Idempotency key membantu API menghadapi timeout dan retry tanpa menggandakan operasi bisnis. Implementasi andal memerlukan kunci unik per tindakan, penyimpanan yang tahan terhadap permintaan bersamaan, pemeriksaan payload, kebijakan masa berlaku, serta autentikasi dan otorisasi yang ketat. Idempotensi adalah bagian dari desain sistem konsisten, bukan sekadar header tambahan.

Referensi

Baca dokumentasi Stripe tentang idempotent requests sebagai contoh pada API pembayaran, serta RFC 9110 tentang metode HTTP idempoten.