Masalah utama saat integrasi API partner adalah memastikan permintaan bisa diulang ulang (retry) tanpa menimbulkan efek samping seperti pemrosesan ganda, sedangkan server tidak menyimpan state session. Kontrak API yang tepat harus menggabungkan otentikasi token, jaminan idempotensi, dan strategi retry yang aman.

Artikel ini menjelaskan elemen kontrak yang praktis: bagaimana menyusun header auth, signature request, idempotensi, logging, serta checklist validasi agar setiap request bisa diulang tanpa risiko duplikat.

Desain Kontrak tanpa Session State

Dalam kontrak API partner tanpa session state, setiap permintaan harus independen. Dependency pada penyimpanan session menyebabkan ketergantungan di server partner dan menghambat retry. Struktur kontrak minimal meliputi:

  • Identitas yang tetap: setiap client memiliki API key atau OAuth client ID.
  • Permintaan lengkap: semua data yang dibutuhkan (payload, context) dikirim ulang pada setiap retry.
  • Metadata idempotensi: header khusus seperti Idempotency-Key memastikan backend tahu apakah request sudah diproses.

Untuk menggambarkan alur, diagram sederhana bisa membantu:

Client -----(1) Authorization Header + Payload-----> API Gateway ----- (2) Request Validation -----> Service Layer
Service Layer ----- (3) Response + Idempotency Status -----> Client

Diagram ini menekankan bahwa gateway tidak menyimpan session state: validasi dilakukan berdasarkan header, payload, dan store idempotensi (bisa key-value store cepat).

Otentikasi Aman dengan Token

Kontrak harus menjelaskan format header otentikasi. Contoh header OAuth 2.0 Bearer:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Atau jika menggunakan API key:

X-API-Key: k1-abc12345

Sertakan juga pendekatan request signature untuk mencegah manipulasi. Misalnya, client menghitung HMAC dari timestamp + method + path + payload:

Signature: HMAC-SHA256(base64(secret), timestamp + method + path + body)

Kontrak harus menyebutkan parameter yang masuk perhitungan signature, bagaimana timestamp divalidasi (misalnya tolerance 5 menit), dan apa yang terjadi apabila signature invalid.

Trade-off: signature menambah keamanan tetapi menuntut sinkronisasi waktu dan ekstra logika pembangkitan. Jika partner tidak bisa menangani signature, minimal gunakan HTTPS dan header nonce untuk mencegah replay.

Idempotensi dan Strategi Retry

Idempotensi kunci agar permintaan bisa di-retry. Kontrak API wajib menjelaskan:

  • Header Idempotency-Key: setiap request memiliki key unik yang dihasilkan client (misalnya UUID atau combination request).
  • Siklus validasi: server memeriksa apakah key sudah ada, jika ya kembalikan response sebelumnya atau status sesuai.
  • TTL idempotensi: batas waktu penyimpanan state idempotensi agar tidak menyimpan data selamanya.

Contoh response:

HTTP/1.1 202 Accepted
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000
Idempotency-Status: processed

Server harus menyimpan minimal status (processed/pending). Jika request gagal di tengah jalan, server mengembalikan status pending sehingga client bisa mengambil tindakan khusus.

Strategi retry terbaik: gunakan exponential backoff dengan jitter agar sistem partner tidak kewalahan. Kontrak harus menyebutkan kode HTTP yang layak di-retry (misalnya 429, 5xx) serta kapan berhenti.

Mitigasi Duplikat, Logging, dan Observabilitas

Untuk mencegah duplikat dan memudahkan debugging, kontrak harus menentukan logging dan observabilitas yang diperlukan:

  • Log request dengan Idempotency-Key dan hasil validasi signature.
  • Correlation ID yang diturunkan dari header custom (misalnya X-Correlation-ID) untuk melacak lintas layanan.
  • Alerting bila ada mismatched signature, TTL idempotensi habis, atau retry loop panjang.

Observabilitas termasuk exposing metrics seperti jumlah request dengan key duplikat, rata-rata latency, dan bagian mana yang paling sering menghasilkan retry. Hal ini membantu memutus apakah masalah ada di client atau server.

Checklist Validasi Kontrak

Gunakan checklist ini saat memfinalisasi kontrak API:

  1. Apakah header otentikasi dijelaskan (OAuth token, API key, atau signature) lengkap dengan contoh?
  2. Apakah ada definisi Idempotency-Key, perilaku saat duplikat, dan TTL penyimpanan?
  3. Apakah retry didefinisikan (kode HTTP yang bisa di-retry, interval, backoff)?
  4. Apakah ada mekanisme signature/nonce untuk melawan replay attack?
  5. Apakah logging/observabilitas (correlation ID, status idempotensi) termasuk dalam kontrak?
  6. Apakah response failure termasuk kode, body, dan cara client mengambil tindakan selanjutnya?

Checklist ini membantu tim partner memvalidasi implementasi mereka sesuai kontrak.

Penutup

Kontrak API yang aman dan dapat di-retry tanpa session state menuntut kombinasi otentikasi token, signature, idempotensi, dan observabilitas lengkap. Dengan dokumentasi yang jelas, contoh header, diagram alur, dan checklist, integrasi partner tetap aman dan bisa diulang tanpa menyebabkan duplikasi.