Untuk mendokumentasikan API Kafka, buatlah kontrak untuk setiap topic. Kontrak tersebut harus mencantumkan nama topic, event key, skema payload, header, jaminan pengurutan dan pengiriman, consumer group, periode retensi, serta pemiliknya. Kemudian simpan kontrak itu di samping dokumentasi HTTP API Anda, agar producer dan consumer membaca satu sumber kebenaran yang sama alih-alih membongkar pesan dari cluster yang sedang berjalan.
Panduan ini membahas setiap bagian dari kontrak tersebut, cara menulisnya dalam AsyncAPI, cara mengevolusikan skema dengan aman, dan cara membiarkan coding agent Anda mengerjakannya dengan Apidog CLI.
Jika Anda baru mengenal desain event-driven, mulailah dengan cara membangun event-driven API dan panduan webhook dan arsitektur event-driven.
Apa itu Kafka API?
Kafka API adalah kumpulan topic, format pesan, dan aturan pengiriman yang digunakan service untuk bertukar event melalui cluster Apache Kafka. Berbeda dengan REST API, tidak ada yang memanggil endpoint dan menunggu respons. Producer menulis record ke topic, consumer membacanya sesuai jadwal masing-masing, dan kontraknya terletak pada bentuk serta makna dari record-record tersebut.
Dokumentasi Kafka menyatakannya dengan gamblang: "sebuah event memiliki key, value, timestamp, dan header metadata opsional." Kafka sendiri tidak memeriksa apa yang ada di dalam value. Producer bisa menulis JSON hari ini dan bentuk JSON yang berbeda besok, dan broker akan menerima keduanya. Itulah sebabnya Kafka API lebih membutuhkan kontrak tertulis dibandingkan HTTP API: tidak ada di lapisan transport yang mencegah perubahan yang merusak (breaking change).
Topic yang tidak terdokumentasi gagal dengan cara yang mudah diprediksi: consumer menebak tipe field dari satu sampel lalu crash saat menemui null, atau service baru tidak tahu bahwa ia menerima setiap pesan minimal sekali dan mengenakan biaya dua kali saat retry.
Apa yang perlu didokumentasikan untuk setiap Kafka topic
Setiap topic membutuhkan fakta-fakta inti yang sama. Gunakan tabel ini sebagai checklist Anda:
| Field kontrak | Apa yang perlu dicatat | Contoh |
|---|---|---|
| Nama topic | Nama lengkap dan konvensi penamaan | orders.order-placed.v1 |
| Tujuan | Satu kalimat tentang makna event tersebut | "Pesanan telah melewati pembayaran dan siap dikirim" |
| Event key | Field mana yang menjadi key, dan alasannya | customerId, agar pesanan satu pelanggan tetap terurut |
| Skema payload | Setiap field, tipe, penanda required, dan format | JSON Schema, Avro, atau Protobuf |
| Header | Nama, tipe, dan makna setiap header | traceparent, schema-version |
| Partisi dan pengurutan | Jumlah partisi dan jaminan pengurutan | 12 partisi, terurut per customerId |
| Semantik pengiriman | At least once, idempotent producer, transaksi | At least once; consumer harus melakukan deduplikasi pada orderId |
| Consumer group | Group yang diketahui dan fungsi masing-masing | billing-service, email-notifier |
| Retensi | Berapa lama record tetap dapat dibaca | 7 hari |
| Kepemilikan | Tim pemilik, kontak, dan kebijakan versi | Tim Checkout, #checkout-events |
Baris pengurutan dan pengiriman paling penting: pembaca tidak bisa menyimpulkannya dari satu contoh pesan.

Cara mendokumentasikan Kafka API dalam 6 langkah
- Catat setiap topic beserta pemiliknya. Ambil daftar topic dari cluster Anda dan tandai siapa yang memproduksi ke masing-masing topic.
- Tentukan key. Tuliskan field mana yang menjadi key dan apa artinya bagi pengurutan.
- Tulis skema payload. Deskripsikan setiap field dengan JSON Schema, Avro, atau Protobuf.
- Jelaskan header dan metadata. Sertakan header untuk tracing, versi skema, dan content type.
- Nyatakan jaminannya. Dokumentasikan semantik pengiriman, cakupan pengurutan, retensi, dan consumer group.
- Publikasikan di tempat yang mudah ditemukan. Letakkan kontrak di samping dokumentasi HTTP API Anda dan versioning seperti kode.
Langkah 1 dan 2: topic dan key
Pola penamaan seperti <domain>.<event>.<version> memberi tahu pembaca siapa pemilik topic dan versi berapa yang sedang dibaca. Kemudian dokumentasikan key, karena key menentukan partisi. Dokumentasi Kafka menyatakan bahwa "event dengan event key yang sama (misalnya ID pelanggan atau kendaraan) ditulis ke partisi yang sama," dan consumer membaca event sebuah partisi "dalam urutan yang persis sama seperti saat ditulis."
Jadi kontrak Anda harus menyatakan "terurut per customerId," bukan sekadar "terurut." Kafka hanya menjamin urutan di dalam satu partisi, tidak pernah di seluruh topic.
Langkah 3: skema payload
Payload adalah bagian yang menjadi acuan consumer dalam menulis kode, jadi deskripsikan field demi field. Berikut JSON Schema untuk event order-placed:
{
"type": "object",
"required": ["orderId", "customerId", "totalCents", "currency", "placedAt"],
"properties": {
"orderId": { "type": "string", "description": "Unique order ID; use it to deduplicate" },
"customerId": { "type": "string", "description": "Also the record key" },
"totalCents": { "type": "integer", "minimum": 0 },
"currency": { "type": "string", "enum": ["USD", "EUR", "GBP"] },
"placedAt": { "type": "string", "format": "date-time" },
"couponCode": { "type": ["string", "null"] }
}
}
Deskripsi "use it to deduplicate" memberi tahu consumer apa yang harus dilakukan dengan field tersebut, bukan hanya tipenya. Baru mengenal format ini? Baca apa itu JSON Schema.
Langkah 4 dan 5: header dan jaminan
Cantumkan setiap header (trace context, versi skema, content type) dan nyatakan apakah consumer bisa mengandalkannya. Kemudian tuliskan jaminan pengiriman dengan istilah Kafka sendiri. Dokumen desain Kafka menyatakan bahwa "Kafka menjamin pengiriman at-least-once secara default," yang berarti pesan "tidak pernah hilang tetapi mungkin dikirim ulang." Jika producer Anda menggunakan opsi idempotent atau transaksi, sebutkan itu. Jika tidak, beri tahu consumer untuk melakukan deduplikasi, dan sebutkan field yang menjadi acuan deduplikasi.
Dokumentasikan juga consumer group. Di dalam setiap group yang berlangganan, sebuah partisi "dikonsumsi tepat oleh satu consumer" pada satu waktu. Ini memberi tahu pembaca seberapa jauh sebuah group bisa scale out: satu consumer aktif per partisi.
Menulis kontrak dalam AsyncAPI
Alat membutuhkan format yang dapat dibaca mesin, dan untuk Kafka format itu biasanya AsyncAPI, sebuah spesifikasi yang "digunakan untuk mendeskripsikan API berbasis pesan dalam format yang dapat dibaca mesin." Ia memainkan peran yang sama seperti OpenAPI untuk REST.
Dokumen AsyncAPI 3.0 memiliki info, servers, channels, operations, dan components. Sebuah channel dipetakan ke sebuah topic melalui address-nya, dan setiap operation memiliki action berupa send atau receive:
asyncapi: 3.0.0
info:
title: Orders events
version: 1.0.0
channels:
orderPlaced:
address: orders.order-placed.v1
messages:
orderPlaced:
$ref: '#/components/messages/orderPlaced'
operations:
publishOrderPlaced:
action: send
channel:
$ref: '#/channels/orderPlaced'
components:
messages:
orderPlaced:
payload:
$ref: './schemas/order-placed.json'
AsyncAPI juga memiliki binding Kafka di level server, channel, operation, dan message. Di sinilah detail spesifik Kafka diletakkan, yaitu hal-hal yang tidak bisa diekspresikan oleh field generik. Simpan spesifikasi di repo producer, agar pull request yang mengubah sebuah event juga mengubah kontraknya.
Evolusi skema Kafka: dokumentasikan aturan kompatibilitas
Skema Anda akan berubah. Kontrak harus menyatakan perubahan mana yang aman. Jika Anda menggunakan schema registry, dokumentasikan mode kompatibilitasnya. Dokumentasi evolusi skema Confluent mencantumkan mode-mode berikut, dan mencatat bahwa "tipe kompatibilitas default Confluent Schema Registry adalah BACKWARD":
| Mode | Siapa dapat membaca apa |
|---|---|
| BACKWARD | Consumer dengan skema baru dapat membaca data yang ditulis dengan skema sebelumnya |
| BACKWARD_TRANSITIVE | Consumer dengan skema baru dapat membaca data dari semua skema sebelumnya |
| FORWARD | Consumer dengan skema sebelumnya dapat membaca data yang ditulis dengan skema baru |
| FORWARD_TRANSITIVE | Consumer dengan skema sebelumnya mana pun dapat membaca data yang ditulis dengan skema baru |
| FULL | Kompatibel mundur dan maju dengan skema sebelumnya |
| FULL_TRANSITIVE | Kompatibel mundur dan maju dengan semua skema sebelumnya |
| NONE | Pemeriksaan kompatibilitas dimatikan |
Dalam praktiknya, dengan BACKWARD Anda bisa menambahkan field opsional dan menghapus field yang memiliki default. Mengganti nama field required atau mengubah tipenya akan merusak consumer. Saat Anda membutuhkan perubahan yang bersifat breaking, publikasikan versi topic baru (orders.order-placed.v2), dokumentasikan keduanya, dan tetapkan tanggal pensiun untuk topic lama.
Biarkan coding agent Anda mendokumentasikan Kafka API dengan Apidog CLI
Kontrak yang ditulis manual akan cepat usang begitu seseorang mengubah producer. Coding agent Anda bisa membaca kode producer, menulis skema, dan menjaga dokumentasi tetap sinkron sementara Anda melakukan review. Apidog CLI memberikan perintah yang dibutuhkan Claude Code, Codex, Cursor, atau agent terminal lain untuk melakukannya di dalam proyek Apidog.
Instal CLI-nya, login, dan tambahkan skill Apidog agar agent Anda mengenal perintah-perintahnya:
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
Anda juga bisa menyerahkan setup kepada agent: beri tahu ia untuk membaca panduan instalasi Apidog CLI dan melakukan setup sendiri.
Kemudian berikan satu prompt kepada agent Anda:
Read the Kafka producers in ./services/orders. For every topic they write to,
create an Apidog data schema in project <projectId> for the message payload,
then create one Markdown doc per topic with the key, headers, ordering,
delivery guarantee, consumer groups, retention and owner. Validate every
payload before you write it.
Agent akan memeriksa bentuk payload, memvalidasi filenya, lalu menulis skema dan halaman kontraknya:
apidog cli-schema get schema-create
apidog cli-schema validate schema-create --file order-placed.schema.json
apidog schema create --project <projectId> --file order-placed.schema.json
apidog cli-schema get doc-create
apidog doc create --project <projectId> --file order-placed.doc.json
apidog schema list --project <projectId>
apidog schema create menyimpan payload sebagai data schema yang dapat digunakan ulang. Endpoint HTTP Anda bisa merujuk ke model yang sama, sehingga Order yang didefinisikan sekali mencakup baik respons REST maupun event Kafka. apidog doc create menulis dokumen Markdown ke dalam struktur proyek, yang menyimpan kontrak topic dari tabel di atas. Ketika producer berubah, jalankan ulang prompt dan agent akan menggunakan apidog schema update. Untuk panduan lebih lengkap tentang pekerjaan dokumentasi berbasis agent, lihat cara mendokumentasikan API dari CLI dan Apidog CLI di Claude Code.

Satu langkah tetap dilakukan di aplikasi. Custom Protocol API milik Apidog mendokumentasikan endpoint Kafka berdampingan dengan endpoint HTTP: pilih New Other Protocol APIs, lalu Other Custom Protocol API, pilih Kafka sebagai protocol, dan isi URI (topic), nama, status, maintainer, tag, dan deskripsi. Entri-entri ini berbagi struktur folder, pencarian, dan Quick Share dengan dokumentasi HTTP Anda. CLI saat ini belum memiliki perintah untuk endpoint custom protocol, jadi ini adalah satu-satunya bagian yang Anda buat secara manual.
Apidog Free mencakup hingga 4 pengguna, sehingga tim kecil bisa menyimpan dokumentasi REST dan Kafka-nya dalam satu proyek tanpa biaya.
FAQ
Apakah ada OpenAPI untuk Kafka?
AsyncAPI mengisi peran tersebut. Ia mendeskripsikan server, channel (topic), operation, dan payload pesan dalam YAML atau JSON, dengan binding khusus Kafka.
Apakah saya membutuhkan schema registry untuk mendokumentasikan Kafka API?
Tidak, tetapi sangat membantu. Dokumentasi menyatakan aturannya; registry menegakkannya saat penulisan. Jika Anda menjalankan salah satunya, dokumentasikan mode kompatibilitasnya.
Apa perbedaan antara mendokumentasikan Kafka topic dan endpoint REST?
Dokumentasi REST mendeskripsikan sebuah request dan respons. Dokumentasi Kafka mendeskripsikan satu pesan yang dibaca oleh banyak consumer di kemudian hari, sehingga juga membutuhkan key, cakupan pengurutan, jaminan pengiriman, retensi, dan consumer group. Semua itu tidak muncul dalam dokumentasi REST pada umumnya.
Bisakah Apidog menguji pesan Kafka?
Apidog mendokumentasikan endpoint Kafka melalui Custom Protocol API, tetapi tidak mengirim atau mengonsumsi pesan Kafka. Gunakan untuk menyimpan kontrak dan skema payload, dan uji kode producer serta consumer dengan library Kafka client Anda.
Seberapa sering saya harus memperbarui dokumentasi Kafka?
Setiap kali producer mengubah sebuah pesan. Kaitkan dengan code review: pull request yang mengubah event juga memperbarui kontraknya, atau agent Anda meregenerasinya dengan Apidog CLI.
