Pengenalan dan Tujuan Kontrak API

Kontrak API idempoten untuk CLI Workspace mendefinisikan ekspektasi konkret terhadap request, response, retry, dan audit agar operasi otomatis tidak merusak keadaan sistem. Menanggapi insiden Fired by Google for creating the Google Workspace CLI, yang menunjukkan bagaimana kegagalan kontrak dan kurangnya perlindungan idempoten dapat menimbulkan masalah besar, kita fokus menciptakan antarmuka yang tahan terhadap retry tak terduga, rate limit, dan kerentanan keamanan.

Pada artikel ini Anda akan menemukan pola autentikasi terukur, rekayasa idempoten server, flow permintaan CLI yang realistis, serta checklist audit keamanan sebelum rilis.

1. Flow Request CLI dan Kontrak Dasarnya

CLI Workspace mengirimkan permintaan terhadap API yang menjalankan operasi seperti buat domain, sinkronkan pengguna, atau konfigurasikan policy. Kontrak API harus memastikan setiap endpoint menerima:

  • HTTP method sesuai (misal POST/PUT untuk mutasi, GET untuk baca).
  • Idempotency-Key di header untuk permintaan mutasi.
  • Payload schema yang tervalidasi, termasuk metadata audit (schema versi, timestamp).
  • Response konsisten: sukses, error terstruktur, dan status code untuk rate limit/duplikasi.

Flow dasar loyal terhadap kontrak:

  1. CLI mendapat OAuth token atau service token dengan scope terbatas.
  2. Permintaan mutasi disertai Idempotency-Key unik dan timeout enforce.
  3. Server mencatat key, memproses permintaan, lalu menyimpan hasil dan status.
  4. Jika CLI mengirim ulang key sama karena timeout atau retry, server mengembalikan hasil sebelumnya tanpa menjalankan ulang operasi.

2. Autentikasi Terukur dan Penyimpanan Secret

Autentikasi harus mendukung scale CLI dan minim dampak jika token bocor. Pola yang disarankan:

  • Service account dengan batas scope terukur: CLI menggunakan JWT yang ditandatangani oleh Vault/Secret Manager, bukan credential statis.
  • Token pendek: misalnya 5 menit, dan refresh otomatis saat diperlukan.
  • Backoff terintegrasi: jika refresh gagal karena rate limit authorization server, CLI menunggu dan log detail.
  • Penyimpanan secret terpusat: kunci private hanya di secret store (HashiCorp Vault, AWS Secrets Manager) dengan rotation otomatis dan audit log.

Dengan pendekatan ini, leak terbatas efeknya. Pastikan juga CLI hanya menyimpan token di memory dan membersihkan sebelum exit.

3. Rekayasa Idempoten Server

Server harus mengubah kontrak jadi proteksi nyata. Pola implementasinya:

  • Persist Idempotency-Key dengan status dan hasil (sukses/gagal). Gunakan tabel deduplikasi atau cache konsisten (Redis dengan durasi cukup lama untuk memcover retry).
  • Lock-free deduplikasi: ketika request datang, server mencoba INSERT key; jika sudah ada, baca response cached.
  • Transaksi komit: operasi mutasi dan cache hasil harus dalam satu transaksi agar state konsisten.

Contoh sederhana response handler:

POST /wallets/create
Headers:
  Idempotency-Key: cli-20240228-1234
  Authorization: Bearer eyJ...

Server:
  if exists(key):
    return cached_response
  begin transaction
  result = create_wallet(payload)
  store key, result.status, result.payload
  commit
  return result

Jika operasi gagal (misalnya karena rate limit downstream), simpan status GAGAL dengan metadata error agar CLI bisa menghindari ambiguitas.

4. Penanganan Retry, Dedup, dan Webhook

Retrying dengan backoff adalah kewajiban CLI, tapi server perlu mendukung deduplikasi dan validasi waktu:

  • Retry CLI: gunakan exponential backoff dengan batas total durasi, jangan retry untuk 4xx (kecuali 409/5xx). Set header Retry-After.
  • Webhook idempoten: jika server memicu webhook (misal notifikasi selesai), sertakan Webhook-Id dan validasi signature. Pastikan webhook juga mendeteksi duplikasi webhook yang sama.
  • Dedup di level side-effects: misalnya saat mengirim email, periksa apakah sudah dikirim berdasarkan event hash.

Trade-off: cache idempotensi memakan storage dan harus dibersihkan. Pilih TTL berdasarkan waktu maksimal CLI mungkin melakukan retry (biasanya beberapa menit). Untuk operasi panjang (batch provisioning), kombinasikan operation_id plus status endpoint.

5. Mitigasi Edge Case: Rate Limit, Rollback, Debugging

Beberapa situasi khusus perlu perhatian:

  • Rate limit: definisikan quota per API key dan global. Jika limit tercapai, berikan response 429 dengan Retry-After. CLI harus menyimpan request untuk percobaan ulang manual dan mencatat ke log.
  • Rollback partial failure: jika operasi multi-step gagal setelah sebagian selesai, gunakan kompensasi eksplisit. Simpan status step dalam tabel; CLI dapat memanggil endpoint khusus untuk membatalkan atau melanjutkan.
  • Debugging: sertakan trace ID dalam header response. CLI harus menyertakan ID ini saat melaporkan bug sehingga backend bisa menelusuri log.

Pastikan setiap retry memeriksa apakah operasi sebelumnya sudah sukses, agar tidak melakukan rollback terhadap perubahan yang sah.

6. Checklist Audit Keamanan Sebelum Rilis

Kontrak API hanya sebaik praktik operasionalnya. Sebelum rilis CLI dan API, pastikan checklist berikut terlewati:

  1. Audit akses secret: pastikan hanya service account CLI yang punya permission baca.
  2. Validasi skema payload: gunakan schema registry atau JSON schema enforce di middleware.
  3. Uji kasus idempoten: kirim ulang request dengan key sama, pastikan tidak menggandakan side-effect.
  4. Simulasi rate limit: pastikan response 429 memuat Retry-After dan CLI menangani backoff.
  5. Penanganan webhook: cek signature dan deduplikasi per Webhook-Id.
  6. Logging dan tracing terintegrasi dengan observability stack (misal log aggregator + trace ID).
  7. Review rollback paths: setiap operasi panjang punya endpoint status dan kompensasi.

Kesimpulan

Kontrak API idempoten untuk CLI Workspace aman menjaga integritas operasi otomatis melalui autentikasi terukur, rekayasa idempoten, pengelolaan secret, dan mitigasi edge case seperti rate limit atau rollback. Context insiden Fired by Google menegaskan pentingnya desain kontrak yang kuat: dengan flow permintaan yang terstruktur, response konsisten, dan checklist keamanan sebelum rilis, CLI bisa tetap pemberdaya tanpa menjadi risiko.