Kontrak API batch idempoten diperlukan saat sistem harus meneruskan rangkaian permintaan ke layanan downstream tanpa mengulang efek bisnis yang sama. Fokus artikel ini adalah menjelaskan mekanisme praktis untuk menjamin idempoten saat memakai autentikasi token OAuth atau API key, serta memastikan klien dan penerima sepakat terhadap versi, retry, dan observabilitas.

Langsung ke inti: tetapkan header idempoten, sertakan versi kontrak, dan gunakan autentikasi tersadari. Berikut langkah-langkah rinci yang bisa diterapkan.

Menetapkan Kontrak Batch Idempoten

Kontrak batch perlu mendefinisikan struktur payload, cara menentukan identitas batch, dan cara menangani operasi multi-request. Setiap batch harus membawa batchId unik dan daftar aksi. Untuk menjaga idempoten, penerima wajib mengecek apakah batchId sudah diproses sebelumnya dan memperlakukan ulang operasi yang sama sebagai nop.

Contoh payload minimal:

{
  "batchId": "3f57e1b9",
  "operations": [
    {"type": "debit", "accountId": "A1", "amount": 100000},
    {"type": "credit", "accountId": "B2", "amount": 100000}
  ]
}

Penerima menyimpan status batch (misalnya: processing, completed, failed) beserta checksum atau versi data. Jika datang request dengan batchId sama, rekap hasil sebelumnya dan kirimkan respons seragam tanpa menjalankan ulang bisnis.

Jangan sekadar mengandalkan HTTP method. Simpan metadata internal dengan expiration, lalu gunakan stored procedure atau log persisten untuk mencatat kemajuan setiap operasi dalam batch.

Autentikasi dan Header Versi

Kontrak harus menentukan apakah autentikasi menggunakan OAuth Bearer token atau API key. Kedua skema bisa hidup berdampingan jika dijelaskan di dokumentasi.

Untuk OAuth, mintalah token dengan scope yang spesifik (misalnya batch.write) dan verifikasi pada penerima dengan introspeksi atau JWT. Untuk API key, masukkan header seperti X-API-Key dan batasi hak akses berdasarkan key.

Selalu sertakan header versi kontrak agar klien dan penerima tidak berbeda persepsi:

X-Contract-Version: 2024-10
Accept: application/json
Idempotency-Key: 3f57e1b9
Authorization: Bearer <token>

X-Contract-Version membantu menangani evolusi payload. Ketika versi berubah, penerima bisa menolak permintaan dengan kode 412 Precondition Failed agar klien memperbarui format. Idempotency-Key adalah header penentu idempoten; nilainya bersifat global minimal per client-service.

Strategi Retry, Backoff, dan Verifikasi Penerima

Retry harus dihadapi dengan hati-hati agar tidak memicu duplikasi. Beberapa prinsip:

  • Retry terbatas: Gunakan retry count terbatas dengan backoff eksponensial. Misalnya, delay 1s, 2s, 4s, lalu stop.
  • Periksa kode status: Tindak lanjuti retry hanya saat status 429, 503, atau timeout jaringan. Jangan retry pada 400+ lain.
  • Trust tapi verify: Klien bisa menambahkan header If-None-Match untuk membantu penerima deteksi perubahan.

Penerima juga perlu membalas status yang mudah dikonsumsi oleh klien, misalnya:

  • 200 OK dengan {