Menjawab langsung: kontrak API idempoten dengan OCaml 5.5

Rilis OCaml 5.5.0 memberi momentum untuk meninjau arsitektur klien API karena peningkatan performa dan dukungan runtime yang lebih stabil. Untuk memastikan klien tetap konsisten dengan kontrak idempoten server, fokus pertama harus pada validasi kontrak dan struktur modul yang eksplisit, lalu pada strategi otentikasi dan retry agar permintaan ulang tidak merusak status sistem.

Di bagian berikut, akan dibahas langkah konkret memetakan kontrak API ke dalam modul OCaml, menjaga header otentikasi tetap aman, serta pola retry/timeout yang aman saat berinteraksi dengan webhook atau integrasi kritis.

Meninjau arsitektur klien API modern di OCaml 5.5

Struktur modul yang memperjelas kontrak

Desain modul harus mencerminkan batas kontrak API. Gunakan module signatures untuk mendefinisikan tipe input/output dan fungsi yang tersedia, sehingga kompilator membantu memastikan konsistensi.

Contoh sederhana:

module type API = sig
  type payload
  type response
  val send : payload -> (response, string) result
end

module Orders : API = struct
  type payload = { id : string; amount : float }
  type response = { status : string; processed_at : string }

  let send payload =
    (* panggilan HTTP + parsing JSON *)
    Ok { status = "queued"; processed_at = "" }
end

Pisahkan modul komunikasi HTTP dari logika serialisasi, sehingga kontrak payload/response tetap kuat saat lapisan transport berubah.

Validasi kontrak saat runtime

Walaupun tipe OCaml kuat, validasi runtime tetap diperlukan karena backend bisa menambah field baru atau mengubah format. Terapkan fungsi validasi yang memeriksa nilai wajib dan pola data sebelum diteruskan ke logika utama.

Gunakan modul parsers yang mengembalikan Json.Decode dengan Result, lalu dokumentasikan skenario kegagalan. Logikanya:

  • Parsing JSON ke tipe yang didefinisikan.
  • Validasi field penting (misalnya idempotency_key wajib untuk operasi penulisan).
  • Penanganan error dengan pesan yang bisa ditelusuri.

Strategi header otentikasi yang aman

Dalam klien OCaml, bungkus header otentikasi ke dalam modul tersendiri agar mudah diuji dan dikonfigurasi untuk lingkungan berbeda. Misalnya, gunakan fungsi wrapper yang menambahkan header Authorization dengan format yang konsisten dan fallback untuk token kadaluarsa.

Jangan menyimpan token di ruang lingkup global; sebagai gantinya, injeksi token lewat konfigurasi atau lingkungan sehingga mudah diganti saat rotasi. Gabungkan juga middleware logging minimal untuk mendeteksi header hilang tanpa mencetak nilai token.

Memastikan retry, timeout, dan idempoten di webhook/integrasi

Pola retry yang menghormati idempoten

Jika backend menjamin idempoten dengan header seperti Idempotency-Key, klien harus mengirim nilai deterministik setiap permintaan ulang. Pastikan key berasal dari kombinasi unik (misalnya resource_id + operation) dan simpan status lokal minimal untuk menghindari duplikasi.

Gunakan pola retry terbatas (contohnya exponential backoff dengan cap) dan pastikan fungsi retry menyertakan alasan (timeout, 5xx). Jangan langsung mengulang pada 4xx kecuali 429 yang ditangani khusus.

Timeout yang terukur

Konfigurasi timeout dua lapis: timeout koneksi untuk fase handshake, dan timeout respons untuk menunggu reply. Gunakan library HTTP yang mendukung pengaturan timeout granular. Catat waktu mulai request agar Anda bisa menyesuaikan retry berikutnya apabila permintaan sebelumnya sudah memasuki fase timeout.

Timeout yang terlalu pendek bisa memicu retry berlebihan, namun terlalu lama membuat webhook menunggu. Ukur latensi backend melalui monitoring dan sesuaikan batas ambang berdasarkan distribusi respons.

Integrasi webhook dengan jaminan idempoten

Untuk webhook, verifikasi signature dari header (misalnya HMAC) sebelum memproses data. Setelah validasi, simpan event_id yang diproses untuk menolak retry identik. Kombinasikan strategi ini dengan pola retry yang hanya memicu ulang pada kegagalan infrastruktur.

Gunakan queue (ex: queue internal) untuk memproses webhook secara asinkron, lalu pastikan ack/response hanya dikirim setelah semua proses selesai. Ini mencegah backend menganggap webhook gagal dan mengirim ulang.

Checklist pengujian integrasi agar kontrak tetap konsisten

  • Snapshot respons: bandingkan skema JSON dengan versi sebelumnya setiap kali backend berubah.
  • Validasi header: pastikan Authorization, Idempotency-Key, dan signature webhook hadir di setiap request.
  • Simulasi retry: jalankan tests yang memicu timeout dan periksa apakah client menghindari duplikasi status.
  • Inject perubahan schema: dalam lingkungan staging, kirim field baru/missing untuk memastikan error handling tidak rusak.
  • Monitoring latensi: rekam waktu respons dan sesuaikan timeout/retry jika ada lonjakan.
  • Audit logging: catat setiap idempotent key dan status pengiriman agar mudah ditelusuri bila terjadi inkonsistensi.

Gunakan kombinasi unit test untuk logika parsing dan integrasi end-to-end untuk perilaku ritme API. Dengan checklist ini distribusi perubahan backend tidak akan serta merta mematahkan kontrak.

Kesimpulan

Dengan rilis OCaml 5.5, sekarang saatnya merakit klien API yang memaknai kontrak idempoten dengan serius: struktur modul yang eksplisit, validasi respons, header otentikasi yang terkelola, serta pola retry dan timeout yang aman. Kombinasikan itu semua dengan checklist pengujian integrasi agar API tetap konsisten sembari backend berevolusi.