Dalam integrasi antar layanan, kegagalan sering tidak terlihat sampai produksi. Sama seperti penulis yang melihat squiggle merah atau hijau ketika kata salah eja, tim platform bisa memakai "spellcheck" kontrak API untuk menangkap kesalahan integrasi sebelum request mencapai sistem lain. Artikel ini langsung menjelaskan pendekatan teknis untuk memvalidasi kontrak, menguji auth, memastikan idempotensi, memverifikasi webhook ack, dan mendefinisikan strategi retry.

Menghubungkan kisah squiggle dengan linting kontrak API

Ketika Raymond Chen menulis tentang orang yang menandai kata dengan garis merah dan hijau, ia menggambarkan gambaran visual instan atas ketidaksesuaian. Dalam arsitektur layanan terdistribusi, kita butuh respons serupa: notifikasi cepat ketika target API berubah, auth mismatch terjadi, atau contract header tak terpenuhi. Kontrak API linting bertugas memberi "squiggle" pada integrasi, memberitahu tim pengirim bahwa request tidak akan diterima dari receiver.

Validasi kontrak: schema linting dan snapshot

Lint OpenAPI atau gRPC schema saat build

Gunakan tooling seperti Spectral (OpenAPI) atau buf lint (Protobuf) sebagai bagian pipeline CI. Konfigurasikan rules yang mengecek kehadiran header wajib, response default, dan field yang tidak boleh berubah secara tiba-tiba. Contoh konfigurasi Spectral:

{
  "extends": "spectral:oas",
  "rules": {
    "info-contact": "error",
    "operation-security": {
      "given": "$.paths.*.*",
      "then": {
        "field": "security",
        "function": "truthy"
      }
    }
  }
}

Linting seperti ini memastikan sebelum dokumen diedarkan, tim backend sudah mendapatkan "squiggle" bila keamanan atau contract berubah.

Snapshot testing untuk kontrak

Tambahkan snapshot contract dalam repository consumers. Ketika kontrak upstream berubah, consumer CI akan gagal karena dibandingkan dengan snapshot yang disimpan. Tooling seperti @openapitools/openapi-generator dengan schema diffs (openapi-diff) membantu mengidentifikasi breaking change secara otomatis.

Validasi kesepakatan autentikasi dan idempotensi

Uji kesepakatan auth

Tetapkan tests yang memanggil endpoint dengan token yang tidak valid, expired, dan token yang hanya memiliki scope minimal. Gunakan test harness untuk memeriksa response status serta body, sehingga mismatch auth langsung terdeteksi di pipeline. Contohnya, gunakan Postman/Newman atau HTTP client dalam test suite:

pm.test("should reject expired token", () => {
  pm.sendRequest({
    url: pm.environment.get("baseUrl") + "/payments",
    headers: { Authorization: "Bearer expired" }
  }, (err, res) => {
    pm.expect(res.status).to.eql(401);
  });
});

Kesalahan auth yang tidak sesuai harus memunculkan "red squiggle" agar tim integrasi tahu token mereka tidak akan diterima.

Mengunci idempotensi

Untuk operasi sensitif (fusion order, billing), definisikan idempotency-key di header. Uji bahwa server menyimpan key dan mengabaikan duplikasi. Gunakan test yang mengirim dua request identik dengan header sama dan memeriksa status tetap 200, sementara request ketiga dengan key berbeda menghasilkan perubahan.

Catat contract linting: tambahkan rule bahwa header Idempotency-Key wajib di schema dan dokumentasikan perilaku response 409 jika key sudah selesai. Bila service tidak menindaki, CI consumer harus gagal sehingga developer tahu keharusan idempotensi belum terpenuhi.

Webhook ack dan strategi retry

Kontrato webhook ack

Webhooks rentan kehilangan payload. Terapkan kontrak yang menetapkan bahwa receiver harus mengirim ack (misal 2xx dalam 100ms). Gunakan simulator untuk memvalidasi time window dan payload signature. Jika ack tidak sesuai, pipeline CI bisa melaporkan definisi kontrak gagal.

Tambahkan test yang memeriksa signature secret dan status ack. Misal, gunakan framework testing untuk mengirim webhook palsu dan memeriksa response handler:

expect(handler({
  headers: { "x-signature": expectedSignature },
  body: payload
})).resolves.toMatchObject({ statusCode: 200 });

Strategi retry sebagai bagian kontrak

Jelaskan retry policy di kontrak: jumlah percobaan, backoff, dan idempotensi. Pastikan setiap consumer memahami bahwa request diterima tetapi diproses ulang jika status belum final. Dokumentasi ini juga membantu debugging ketika integrasi gagal, misalnya ketika queue retry berulang menandakan downstream overload.

Sertakan konfigurasi konkret pada system seperti AWS Lambda + SQS, atau Kafka: tombol retry harus dikodekan, disertai dead-letter queue (DLQ) untuk intercept kesalahan yang tak terdeteksi. Catat bahwa terlalu banyak retry tanpa idempotensi menyebabkan duplikasi, jadi lint pipeline harus menandai contract yang tidak menyebutkan idempotensi, ack, dan retry policy secara eksplisit.

Checklist pengujian integrasi untuk tim backend/platform

  • Lint kontrak: spectral/buf lint menyala tanpa error.
  • Snapshot contract: CI consumer memverifikasi contract terbaru bukan breaking change.
  • Auth alignment: tests dengan token valid, expired, scope kurang.
  • Idempotensi: test konfigurasi Idempotency-Key dan duplikasi.
  • Webhook ack: simulator memberikan response dalam SLA, signature valid.
  • Retry policy: dokumentasi retry/backoff, monitoring DLQ.
  • Monitoring error: alert saat kontrak linting gagal atau webhook ack timeouts.

Checklist ini memfasilitasi tim mengetahui jika integrasi menyimpang sebelum user merasakannya.

Tooling praktis dan pipeline

Gabungkan linting dan contract testing ke pipeline CI/CD. Contoh: sebelum deploy, jalankan npm run lint:spectral dan npm run test:contracts—tools yang mendeteksi perbedaan schema, auth, dan webhook ack.

Untuk monitoring runtime, gunakan observabilitas (OpenTelemetry) untuk memonitor retry count, webhook ack latency, dan response auth errors. Bila jumlah retry naik atau ack timeout muncul, sistem alert bisa menandai bagian integrasi sebagaimana squiggle merah.

Penutup

Dengan menerapkan contract linting yang menyeluruh, validasi auth, idempotensi, webhook ack, dan strategi retry, tim backend dan platform bisa menangkap integrasi gagal sedini spellcheck. Setiap kesalahan terdeteksi di pipeline sebelum merusak experience, dan setiap penemuan di-telemetri layaknya garis merah yang memperingatkan developer.