Kontrak API Ketat: Cegah Drift pada Auth dan Retry Integrasi

Kontrak API ketat adalah cara paling efektif untuk mencegah integrasi rapuh saat mekanisme autentikasi berubah, retry ditambahkan, atau sistem internal dioptimasi besar-besaran. Selama boundary eksternal tetap stabil, Anda bisa mengganti parser, queue, database, atau arsitektur internal tanpa mematahkan klien.

Prinsip ini mirip dengan pelajaran dari optimasi parser PostHog: perubahan internal boleh agresif selama perilaku yang dijanjikan ke luar tetap konsisten. Untuk API, itu berarti format request/response, header auth, error model, retry semantics, webhook verification, dan compatibility rules harus dianggap sebagai contract, bukan detail implementasi yang boleh berubah diam-diam.

Mengapa contract drift sering terjadi

Contract drift muncul ketika implementasi internal diam-diam mengubah perilaku eksternal. Masalahnya tidak selalu berupa perubahan path endpoint. Justru yang sering mematahkan integrasi adalah hal-hal kecil seperti:

Header auth yang tadinya opsional menjadi wajib tanpa transisi.
Kode error berubah dari 401 ke 403, lalu klien gagal melakukan refresh token.
Retry server menyebabkan efek samping ganda karena endpoint tidak idempoten.
Field respons yang dulu selalu ada tiba-tiba hilang saat refactor serializer.
Tanda tangan webhook dihitung ulang dengan canonicalization berbeda.
Timeout dipersingkat tanpa mendokumentasikan ekspektasi retry di sisi klien.

Jika boundary API jelas, optimasi internal dapat berlangsung aman. Jika boundary longgar, perubahan kecil di auth atau retry akan terasa seperti breaking change.

Definisikan boundary eksternal yang tidak boleh berubah sembarangan

Mulailah dengan mendokumentasikan apa saja yang termasuk kontrak publik. Banyak tim hanya menganggap schema JSON sebagai kontrak, padahal untuk integrasi nyata kontraknya lebih luas.

Komponen kontrak yang wajib eksplisit

Endpoint dan method HTTP: path, verb, media type, dan aturan query parameter.
Header auth: format Authorization, header tambahan, masa berlaku token, dan respons saat gagal.
Idempotency semantics: endpoint mana yang mendukung retry aman, bagaimana perilaku duplicate request, dan TTL penyimpanan key.
Error model stabil: struktur body error, daftar code yang dapat diandalkan, dan perbedaan retryable vs non-retryable.
Timeout contract: perkiraan latensi, apakah operasi async, kapan klien sebaiknya polling.
Webhook verification: algoritma signature, source timestamp, window toleransi, dan payload canonicalization.
Backward compatibility rules: field baru boleh ditambah, field lama tidak boleh dihapus tanpa versi baru.

Aturan praktis: jika klien perlu mengetahuinya agar integrasi tetap benar, maka itu bagian dari kontrak dan tidak boleh berubah diam-diam.

Versioning kontrak: pisahkan perubahan internal dari perubahan publik

Versioning bukan hanya menaruh /v1 di URL. Tujuannya adalah memberi ruang untuk evolusi publik secara terkendali. Jika perubahan hanya internal, tidak perlu versi baru. Jika perubahan mengubah ekspektasi klien, perlakukan sebagai perubahan kontrak.

Kapan perlu versi baru

Menghapus field yang sebelumnya selalu ada.
Mengubah arti field atau satuan nilainya.
Mengubah aturan auth yang mewajibkan header atau flow baru.
Mengubah format error yang digunakan klien untuk branching logic.
Mengubah semantics retry atau idempotency.

Kapan tidak perlu versi baru

Mengganti parser atau storage internal tanpa perubahan output kontrak.
Menambah field baru yang benar-benar opsional.
Meningkatkan performa atau concurrency internal.
Memindahkan eksekusi ke worker async selama kontrak respons tetap sama atau ada transisi yang jelas.

Penting untuk membedakan schema compatibility dan behavior compatibility. Schema bisa tetap sama, tetapi perilaku bisa berubah. Contoh: respons masih 200 dengan body yang sama, namun server kini memproses operasi secara async sehingga data belum langsung tersedia. Bagi klien, itu tetap bisa menjadi breaking change jika sebelumnya mereka mengandalkan konsistensi sinkron.

Rancang auth yang ketat dan stabil

Auth adalah area yang paling sering mengalami drift karena tim keamanan, gateway, atau infrastruktur sering menambah lapisan baru. Agar integrasi tidak rapuh, kontrak auth harus sesederhana mungkin dan konsisten.

Header auth yang jelas

Jika menggunakan bearer token, tentukan satu bentuk resmi dan pertahankan:

Authorization: Bearer <token>

Jangan mendukung banyak variasi tanpa alasan kuat, misalnya kadang token di query string, kadang di header custom. Variasi seperti itu mempersulit debugging, meningkatkan risiko kebocoran kredensial, dan membuat gateway/proxy sulit diaudit.

Bedakan 401 dan 403 secara konsisten

401 Unauthorized: token tidak ada, format salah, kedaluwarsa, atau tidak valid.
403 Forbidden: identitas valid, tetapi tidak berhak mengakses resource/aksi.

Pemisahan ini penting karena banyak klien melakukan refresh token otomatis hanya saat 401. Jika server tiba-tiba mengganti semuanya menjadi 403, alur pemulihan di klien bisa rusak.

Contoh respons error auth yang stabil

{
  "error": {
    "code": "AUTH_INVALID_TOKEN",
    "message": "Token tidak valid atau telah kedaluwarsa",
    "retryable": false,
    "request_id": "req_7f2c9d1a"
  }
}

Gunakan code yang stabil untuk logic mesin. message boleh dibaca manusia dan dapat lebih fleksibel. Menjadikan klien bergantung pada isi message adalah sumber drift klasik.

Retry aman memerlukan idempotency key dan error model stabil

Retry sering ditambahkan belakangan saat sistem mengalami timeout, gangguan jaringan, atau failover. Masalahnya, retry tanpa kontrak yang jelas dapat membuat efek samping ganda: order tercipta dua kali, invoice terbit berulang, atau token direvoke lebih dari sekali.

Kapan endpoint perlu idempotency key

Gunakan idempotency key untuk operasi tulis yang bisa dipicu ulang oleh klien atau proxy, terutama POST yang membuat resource atau memicu side effect. Klien mengirim key unik per operasi logis:

POST /payments
Authorization: Bearer <token>
Idempotency-Key: 3f0c2b83-0c46-4c6d-8ec6-2af4f9780a13
Content-Type: application/json

Server menyimpan hasil pertama untuk kombinasi yang relevan, biasanya berdasarkan Idempotency-Key ditambah identitas tenant atau akun. Jika request identik diulang, server mengembalikan hasil yang sama alih-alih mengeksekusi ulang side effect.

Contoh request/response idempoten

{
  "amount": 150000,
  "currency": "IDR",
  "external_reference": "order-2026-00091"
}

{
  "data": {
    "payment_id": "pay_01JXYZ...",
    "status": "accepted",
    "amount": 150000,
    "currency": "IDR"
  },
  "meta": {
    "idempotency_replayed": false,
    "request_id": "req_a12b34c5"
  }
}

Ketika request yang sama diretry:

{
  "data": {
    "payment_id": "pay_01JXYZ...",
    "status": "accepted",
    "amount": 150000,
    "currency": "IDR"
  },
  "meta": {
    "idempotency_replayed": true,
    "request_id": "req_d67e89f0"
  }
}

Aturan penting untuk idempotency

Jika payload berbeda tetapi Idempotency-Key sama, kembalikan error konflik, jangan diam-diam memproses salah satunya.
Simpan hasil berdasarkan scope yang aman, misalnya per akun atau tenant, agar key dari klien lain tidak bentrok.
Dokumentasikan masa retensi key. Jika key kedaluwarsa, klien harus tahu risiko operasi diproses ulang.
Pastikan penyimpanan idempotency berada di boundary yang andal; cache volatil tanpa strategi pemulihan bisa menyebabkan replay ganda saat restart.

Error model stabil untuk keputusan retry

Klien perlu tahu kapan aman untuk retry. Jangan paksa mereka menebak dari status code saja. Sertakan sinyal eksplisit.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Terlalu banyak request",
    "retryable": true,
    "retry_after_seconds": 30,
    "request_id": "req_f1e2d3c4"
  }
}

Praktik baik:

429 untuk rate limit, opsional dengan Retry-After.
503 untuk gangguan sementara atau overload.
400/422 untuk input salah yang tidak layak diretry tanpa perubahan.
409 untuk konflik, termasuk mismatch idempotency payload.

Jika Anda menandai retryable: true, pastikan backend benar-benar siap menerima request ulang tanpa side effect tak terduga.

Timeout dan retry policy harus menjadi bagian dari kontrak

Banyak integrasi gagal bukan karena schema berubah, melainkan karena ekspektasi waktu tidak cocok. Server menganggap klien akan menunggu lama, sedangkan klien memiliki timeout pendek dan melakukan retry agresif. Hasilnya: duplicate work, thundering herd, atau status yang membingungkan.

Apa yang perlu didokumentasikan

Batas waktu respons yang realistis untuk endpoint sinkron.
Operasi mana yang sebaiknya async dengan polling atau webhook.
Apakah klien boleh retry pada timeout jaringan.
Backoff yang disarankan, misalnya exponential backoff dengan jitter.
Apakah server mengembalikan request ID untuk pelacakan saat hasil tidak pasti.

Contoh pendekatan praktis

Untuk operasi yang bisa memakan waktu lama, lebih aman kembalikan status penerimaan daripada menahan koneksi terlalu lama:

{
  "data": {
    "job_id": "job_9ab3ef",
    "status": "pending"
  },
  "links": {
    "self": "/jobs/job_9ab3ef"
  }
}

Pola ini mengurangi timeout ambigu. Klien tidak perlu menebak apakah operasi berhasil sebelum koneksi putus.

Webhook signature: kontrak keamanan yang sering rusak saat refactor

Webhook sering gagal bukan karena bisnis logic, tetapi karena aturan verifikasi berubah tipis: urutan header berubah, body diparse lalu diserialisasi ulang, atau algoritma canonicalization berganti. Signature webhook harus didefinisikan sangat ketat.

Aturan yang sebaiknya eksplisit

Header mana yang membawa signature, misalnya X-Signature.
Header timestamp yang ikut ditandatangani.
Apakah signature dihitung dari raw request body atau JSON yang telah diparse.
Algoritma HMAC yang digunakan.
Format encoding hasil, misalnya hex atau base64.
Batas toleransi timestamp untuk mencegah replay attack.

Contoh verifikasi konseptual

signed_payload = timestamp + "." + raw_body
expected = HMAC(secret, signed_payload)
constant_time_compare(expected, received_signature)

Poin pentingnya adalah raw_body. Banyak implementasi rusak karena body JSON diparse lalu di-serialize ulang, sehingga whitespace atau urutan field berubah dan signature tidak lagi cocok.

Contoh request webhook

POST /webhooks/posthog-parser
X-Webhook-Timestamp: 1734567890
X-Webhook-Signature: v1=8f1c...
Content-Type: application/json

{
  "event": "parser.completed",
  "data": {
    "job_id": "job_9ab3ef",
    "result_version": "2026-01",
    "status": "success"
  }
}

Belajar dari konteks parser PostHog: internal boleh berubah, output publik jangan

Dalam konteks parser seperti yang dibahas PostHog, tim bisa melakukan optimasi internal besar: mengganti strategi parsing, mempercepat AST generation, memindahkan komponen ke bahasa atau modul lain, atau menambah cache. Semua itu aman selama boundary eksternal tetap jelas.

Untuk API integrasi, analoginya seperti ini:

Anda boleh mengganti parser SQL internal, tetapi jangan mengubah struktur respons tanpa versi baru.
Anda boleh memindahkan auth validation ke gateway, tetapi jangan mengubah semantics 401/403 seenaknya.
Anda boleh menambahkan retry internal ke downstream service, tetapi endpoint publik tetap harus idempoten.
Anda boleh mengubah pipeline async, tetapi jika hasil tidak lagi sinkron, itu perubahan kontrak yang harus diekspos dengan benar.

Intinya, optimasi internal seharusnya tidak bocor sebagai kejutan ke konsumen API.

Backward compatibility yang benar-benar praktis

Backward compatibility bukan sekadar janji. Ia perlu aturan operasional yang bisa dipakai reviewer dan CI.

Aturan aman yang umum dipakai

Menambah field respons baru diperbolehkan jika klien tidak wajib memahaminya.
Jangan mengubah tipe field yang sudah ada, misalnya integer menjadi string.
Jangan mengganti nullability tanpa analisis dampak.
Jangan ubah arti enum yang sudah dipublikasikan.
Jangan hapus field atau status code tanpa versi baru atau masa deprecation yang jelas.
Jika field lama akan ditinggalkan, beri periode transisi dan telemetry penggunaan.

Kesalahan umum

Menganggap urutan field JSON penting lalu mengubah serializer dan memicu bug di klien yang salah implementasi.
Mengubah pesan error untuk manusia dan tanpa sadar mematahkan parser klien yang melakukan string matching.
Mengembalikan 200 dengan body error non-standar agar “lebih mudah”, padahal merusak tooling HTTP.
Mengubah default timeout atau retry di gateway tanpa koordinasi dengan tim API.

Observability untuk mendeteksi contract drift lebih awal

Contract drift jarang terdeteksi di unit test biasa. Anda memerlukan observability yang melihat perilaku nyata di perbatasan sistem.

Sinyal yang perlu dicatat

Request ID pada setiap respons dan log server.
Version tag kontrak atau schema yang dipakai oleh endpoint.
Distribusi status code, khususnya lonjakan 401, 403, 409, 429, dan 5xx.
Idempotency replay rate dan konflik key.
Webhook verification failure rate.
Client fingerprint atau consumer ID bila tersedia, untuk melihat klien mana yang terdampak.
Diff payload sampling untuk membandingkan bentuk respons lama vs baru pada canary release.

Contract test dan shadow traffic

Selain observability runtime, gunakan:

Consumer-driven contract test bila Anda memiliki sejumlah konsumen yang diketahui.
Schema validation di CI untuk request/response.
Golden file test untuk respons endpoint kritis.
Shadow traffic atau canary untuk membandingkan hasil implementasi lama dan baru tanpa langsung mengubah semua trafik.

Untuk perubahan internal besar seperti parser atau auth middleware, shadow traffic sangat berguna: request diproses dua jalur, lalu output dibandingkan. Jika ada selisih pada status, body, atau header kontraktual, rollout dihentikan.

Contoh spesifikasi respons yang lebih tahan perubahan

Berikut contoh respons sukses dan error dengan struktur yang konsisten:

{
  "data": {
    "id": "prs_12345",
    "status": "completed",
    "result": {
      "tables": ["events", "users"],
      "warnings": []
    }
  },
  "meta": {
    "request_id": "req_123abc",
    "contract_version": "2026-01"
  }
}

{
  "error": {
    "code": "PARSER_TIMEOUT",
    "message": "Pemrosesan melebihi batas waktu",
    "retryable": true,
    "request_id": "req_456def"
  }
}

Struktur semacam ini membantu karena:

data dan error memisahkan jalur sukses dan gagal.
code stabil untuk automasi.
request_id memudahkan tracing lintas service.
contract_version membantu audit saat ada perbedaan perilaku.

Edge case yang sering terlewat

Retry datang setelah operasi pertama sukses, tetapi respons pertama hilang karena timeout jaringan.
Klien mengirim Idempotency-Key yang sama untuk payload berbeda.
Gateway menghapus header custom sehingga auth atau signature gagal.
Clock skew membuat validasi timestamp webhook sering ditolak.
Serializer baru menghilangkan field kosong yang sebelumnya selalu ada.
Perubahan internal membuat operasi yang dulu sinkron menjadi eventual consistent.
Token valid, tetapi scope berubah sehingga respons auth bergeser dari 200 ke 403.
Klien melakukan retry paralel dengan key yang sama dan memicu race condition di server.
Error downstream dibungkus menjadi 500 generik, padahal sebelumnya klien bisa membedakan 429 vs 503.
Body webhook dikompresi atau dinormalisasi oleh proxy sebelum signature diverifikasi.

Checklist review API sebelum rilis

Apakah perubahan ini mengubah kontrak publik atau hanya implementasi internal?
Apakah status code 401, 403, 409, 429, dan 5xx tetap konsisten?
Apakah format Authorization dan header terkait tetap sama?
Apakah endpoint tulis yang bisa diretry sudah mendukung idempotency key?
Apakah duplicate request mengembalikan hasil yang konsisten?
Apakah ada perubahan pada struktur error, code error, atau field retryability?
Apakah timeout baru mengubah perilaku yang dirasakan klien?
Jika operasi kini async, apakah ada endpoint status atau webhook yang terdokumentasi?
Apakah signature webhook masih dihitung dari raw body dengan aturan canonicalization yang sama?
Apakah field yang dihapus atau diubah tipenya sudah melalui strategi versioning/deprecation?
Apakah observability sudah menangkap request ID, error code, contract version, dan verification failure?
Apakah ada contract test atau golden test untuk endpoint kritis?
Apakah shadow traffic atau canary menunjukkan output lama dan baru setara pada boundary publik?
Apakah dokumentasi klien telah diperbarui jika ada perubahan perilaku yang sah?

Penutup

Kontrak API ketat bukan berarti sistem menjadi kaku. Justru sebaliknya: kontrak yang jelas memberi kebebasan untuk mengubah internal secara agresif tanpa merusak integrasi. Seperti pada konteks parser PostHog, optimasi besar di balik layar aman dilakukan jika input-output publik, semantics auth, retry, error model, dan observability dijaga sebagai boundary yang tegas.

Jika Anda ingin integrasi tahan terhadap refactor, mulai dari hal paling menentukan: versioning yang disiplin, auth yang konsisten, idempotency key untuk operasi tulis, error model stabil, verifikasi webhook yang presisi, dan telemetry untuk mendeteksi drift sebelum klien yang menemukannya.

Quick Search

shopping_cart Keranjang