Kafka API'leri Nasıl Dokümante Edilir: Topic'ler, Şemalar ve Sözleşmeler

Bir Kafka topic'inin okunacak bir uç noktası yoktur; bu yüzden sözleşmesinin yazılı olarak kaydedilmesi gerekir. Her topic için neyi belgelemeniz gerektiğini, bunu AsyncAPI ile nasıl ifade edeceğinizi ve kodlama ajanınızın bu belgeyi nasıl güncel tutabileceğini burada bulabilirsiniz.

Ashley Innocent

Ashley Innocent

16 November 2026

Kafka API'leri Nasıl Dokümante Edilir: Topic'ler, Şemalar ve Sözleşmeler

Kurumsal İçin Apidog

Şirket İçi (On-Premises) Dağıtım

SSO ve RBAC

SOC 2 Uyumlu

Apidog Enterprise'ı Keşfedin

Kafka API'lerini belgelemek için her topic için bir sözleşme yazın. Bu sözleşme topic adını, event anahtarını, payload şemasını, header'ları, sıralama ve teslimat garantilerini, consumer group'ları, saklama süresini ve sahibini içermelidir. Ardından bu sözleşmeyi HTTP API dokümanlarınızın yanına koyun; böylece üreticiler ve tüketiciler canlı bir kümeden mesajları tersine mühendislikle çözümlemek yerine tek bir güvenilir kaynaktan okur.

Bu rehber, o sözleşmenin her bölümünü, AsyncAPI ile nasıl yazılacağını, şemaların güvenli şekilde nasıl evrileceğini ve Apidog CLI ile bu işi kodlama ajanınıza nasıl yaptırabileceğinizi kapsar.

Event-driven tasarıma yeniyseniz, önce event-driven API'ler nasıl oluşturulur ve webhook'lar ve event-driven mimari rehberi makalelerine göz atın.

Kafka API Nedir?

Bir Kafka API, servislerin bir Apache Kafka kümesi üzerinden event alışverişi yapmak için kullandığı topic'ler, mesaj formatları ve teslimat kuralları bütünüdür. REST API'nin aksine, kimse bir endpoint'i çağırıp yanıt beklemez. Producer'lar kayıtları topic'lere yazar, consumer'lar kendi zamanlamalarına göre okur ve sözleşme, o kayıtların biçiminde ve anlamında yaşar.

Kafka dokümantasyonu bunu açıkça ifade eder: "bir event'in bir key, value, timestamp ve isteğe bağlı metadata header'ları vardır." Kafka, value'nun içinde ne olduğunu denetlemez. Bir producer bir gün JSON yazıp ertesi gün farklı bir JSON yapısı yazabilir ve broker ikisini de kabul eder. İşte bu yüzden Kafka API'leri, HTTP API'lerinden daha çok yazılı sözleşmelere ihtiyaç duyar: taşıma katmanında hiçbir şey bozan bir değişikliği engelleyemez.

Belgelenmemiş topic'ler öngörülebilir şekillerde başarısız olur: bir consumer tek bir örnekten alan tipini tahmin eder ve null değeriyle çöker, ya da yeni bir servis her mesajı en az bir kez aldığını bilmez ve retry'larda çift faturalama yapar.

Her Kafka topic'i için ne belgelenmeli

Her topic aynı temel bilgilere ihtiyaç duyar. Bu tabloyu kontrol listesi olarak kullanın:

Sözleşme alanı Ne yazılmalı Örnek
Topic adı Tam ad ve adlandırma kuralı orders.order-placed.v1
Amaç Event'in ne anlama geldiğine dair tek cümle "Bir sipariş ödemeyi geçti ve kargoya hazır"
Event anahtarı Hangi alanın anahtar olduğu ve neden customerId, böylece bir müşterinin siparişleri sıralı kalır
Payload şeması Her alan, tip, zorunluluk bayrağı ve format JSON Schema, Avro veya Protobuf
Header'lar Her header'ın adı, tipi ve anlamı traceparent, schema-version
Partition'lar ve sıralama Partition sayısı ve sıralama garantisi 12 partition, customerId başına sıralı
Teslimat semantiği En az bir kez, idempotent producer, transaction'lar En az bir kez; consumer'lar orderId üzerinden tekrarları ayıklamalı
Consumer group'ları Bilinen group'lar ve her birinin yaptığı iş billing-service, email-notifier
Saklama Kayıtlar ne kadar süre okunabilir kalıyor 7 gün
Sahiplik Sahip ekip, iletişim kanalı ve sürüm politikası Checkout ekibi, #checkout-events

Sıralama ve teslimat satırları en kritik olanlar: okuyucular bunları örnek bir mesajdan çıkaramaz.

Kafka topic sözleşmesi şeması: bir producer anahtarlanmış event'leri iki consumer group'un okuduğu bir partitionlı topic'e yazar, sözleşme alanları yanında

Kafka API'lerini 6 adımda belgeleme

  1. Her topic'i ve sahibini listeleyin. Kümenizden topic listesini çekin ve her birine kimin üretim yaptığını işaretleyin.
  2. Anahtarı tanımlayın. Hangi alanın anahtar olduğunu ve bunun sıralama için ne anlama geldiğini yazın.
  3. Payload şemasını yazın. Her alanı JSON Schema, Avro veya Protobuf ile tanımlayın.
  4. Header'ları ve metadata'yı açıklayın. Tracing, şema sürümü ve content type header'larını ekleyin.
  5. Garantileri belirtin. Teslimat semantiğini, sıralama kapsamını, saklama süresini ve consumer group'ları belgeleyin.
  6. İnsanların bakacağı yerde yayınlayın. Sözleşmeyi HTTP API dokümanlarınızın yanına koyun ve kod gibi sürümleyin.

1. ve 2. adım: topic'ler ve anahtarlar

<domain>.<event>.<version> gibi bir adlandırma deseni, okuyuculara topic'in kime ait olduğunu ve hangi sürümü okuduklarını söyler. Ardından anahtarı belgeleyin, çünkü partition'ı o belirler. Kafka'nın dokümanları, "aynı event anahtarına sahip event'lerin (örneğin bir müşteri veya araç kimliği) aynı partition'a yazıldığını" ve consumer'ların bir partition'ın event'lerini "yazıldıkları sıranın birebir aynısıyla" okuduğunu belirtir.

Bu yüzden sözleşmeniz "sıralı" değil, "customerId başına sıralı" demelidir. Kafka yalnızca bir partition içindeki sırayı garanti eder, tüm topic için asla.

3. adım: payload şeması

Payload, consumer'ların kod yazarken dayandığı kısımdır, bu yüzden alan alan tanımlayın. İşte bir order-placed event'i için JSON Schema örneği:

{
  "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"] }
  }
}

"use it to deduplicate" açıklaması, consumer'a alanın ne işe yaradığını söyler, yalnızca tipini değil. Bu formatta yeniyseniz JSON Schema nedir makalesini okuyun.

4. ve 5. adım: header'lar ve garantiler

Her header'ı listeleyin (trace bağlamı, şema sürümü, content type) ve consumer'ların buna güvenip güvenemeyeceğini belirtin. Ardından teslimat garantisini, Kafka'nın kendi terimleriyle yazın. Kafka tasarım dokümanları, "Kafka'nın varsayılan olarak at-least-once teslimatı garanti ettiğini" ve bu sayede mesajların "asla kaybolmadığını ancak yeniden teslim edilebileceğini" belirtir. Producer'ınız idempotent seçeneğini veya transaction'ları kullanıyorsa, bunu belirtin. Kullanmıyorsa, consumer'lara tekrarları ayıklamalarını söyleyin ve hangi alana göre ayıklamaları gerektiğini adlandırın.

Consumer group'ları da belgeleyin. Abone olan her group içinde bir partition'a aynı anda "tam olarak bir consumer" sahiptir. Bu, okuyuculara bir group'un ne kadar ölçeklenebileceğini söyler: partition başına bir aktif consumer.

Sözleşmeyi AsyncAPI ile yazın

Araçlar makine tarafından okunabilir bir formata ihtiyaç duyar ve Kafka için bu genellikle "mesaj tabanlı API'leri makine tarafından okunabilir bir formatta tanımlamak için kullanılan" AsyncAPI'dir. REST için OpenAPI'nin üstlendiği rolü üstlenir.

Bir AsyncAPI 3.0 belgesi info, servers, channels, operations ve components bölümlerine sahiptir. Bir channel, address üzerinden bir topic'e karşılık gelir ve her operation send veya receive türünde bir action'a sahiptir:

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 ayrıca sunucu, channel, operation ve mesaj düzeyinde Kafka binding'lerine sahiptir. Kafka'ya özgü detaylar, yani genel alanların ifade edemediği bilgiler buraya yazılır. Spesifikasyonu producer'ın reposunda tutun, böylece bir event'i değiştiren pull request sözleşmeyi de değiştirir.

Kafka şema evrimi: uyumluluk kuralını belgeleyin

Şemanız zamanla değişecek. Sözleşme, hangi değişikliklerin güvenli olduğunu söylemelidir. Bir schema registry kullanıyorsanız, uyumluluk modunu belgeleyin. Confluent'ın şema evrimi dokümanları bu modları listeler ve "Confluent Schema Registry'nin varsayılan uyumluluk tipinin BACKWARD" olduğunu belirtir:

Mod Kim neyi okuyabilir
BACKWARD Yeni şemadaki consumer'lar, önceki şemayla yazılmış verileri okuyabilir
BACKWARD_TRANSITIVE Yeni şemadaki consumer'lar, tüm önceki şemalarla yazılmış verileri okuyabilir
FORWARD Önceki şemadaki consumer'lar, yeni şemayla yazılmış verileri okuyabilir
FORWARD_TRANSITIVE Önceki herhangi bir şemadaki consumer'lar, yeni şemayla yazılmış verileri okuyabilir
FULL Önceki şemayla hem geri hem ileri yönlü uyumlu
FULL_TRANSITIVE Tüm önceki şemalarla hem geri hem ileri yönlü uyumlu
NONE Uyumluluk kontrolleri kapalı

Pratikte, BACKWARD altında isteğe bağlı alanlar ekleyebilir ve varsayılan değeri olan alanları kaldırabilirsiniz. Zorunlu bir alanı yeniden adlandırmak veya tipini değiştirmek consumer'ları bozar. Bozan bir değişikliğe ihtiyacınız olduğunda, yeni bir topic sürümü yayınlayın (orders.order-placed.v2), ikisini de belgeleyin ve eski sürüm için bir emeklilik tarihi belirleyin.

Kodlama ajanınızın Apidog CLI ile Kafka API'lerini belgelemesini sağlayın

Elle yazılan sözleşmeler, biri producer'ı değiştirdiği anda güncelliğini yitirir. Kodlama ajanınız producer kodunu okuyabilir, şemaları yazabilir ve siz onaylarken dokümanları senkron tutabilir. Apidog CLI, Claude Code, Codex, Cursor veya herhangi bir terminal ajanına bunu bir Apidog projesinde yapması için gereken komutları sunar.

CLI'ı kurun, giriş yapın ve ajanınızın komutları bilmesi için Apidog skill'ini ekleyin:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

Kurulumu da ajana devredebilirsiniz: ona Apidog CLI kurulum rehberini okuyup kendini kurmasını söyleyin.

Ardından ajanınıza tek bir prompt verin:

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.

Ajan payload yapısını kontrol eder, dosyasını doğrular, ardından şemayı ve sözleşme sayfasını yazar:

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, payload'u yeniden kullanılabilir bir veri şeması olarak kaydeder. HTTP endpoint'leriniz aynı modele referans verebilir, böylece bir kez tanımlanan bir Order hem REST yanıtını hem Kafka event'ini kapsar. apidog doc create, proje ağacına yukarıdaki tablodaki topic sözleşmesini barındıran bir Markdown belgesi yazar. Bir producer değiştiğinde prompt'u yeniden çalıştırın ve ajan apidog schema update kullanır. Ajan odaklı dokümantasyon işinin daha uzun bir anlatımı için API'ler CLI'dan nasıl belgelenir ve Claude Code'da Apidog CLI makalelerine bakın.

İş akışı şeması: bir kodlama ajanı producer kodunu okur ve apidog schema create ile apidog doc create komutlarını tek bir Apidog projesine çalıştırır

Tek bir adım uygulamada kalır. Apidog'un Custom Protocol API özelliği, Kafka endpoint'lerini HTTP endpoint'lerle birlikte belgeler: Yeni Diğer Protokol API'leri'ni seçin, ardından Diğer Özel Protokol API'yi seçin, protokol olarak Kafka'yı seçin ve URI'yi (topic), adı, durumu, sorumluları, etiketleri ve açıklamayı doldurun. Bu kayıtlar, HTTP dokümanlarınızla aynı klasör ağacını, aramayı ve Quick Share'i paylaşır. CLI'ın bugün özel protokol endpoint'leri için bir komutu yok, bu yüzden elle oluşturduğunuz tek kısım burasıdır.

Apidog Free 4 kullanıcıya kadar kapsar, böylece küçük bir ekip REST ve Kafka dokümanlarını tek projede ücretsiz tutabilir.

SSS

Kafka için bir OpenAPI var mı?

AsyncAPI bu rolü üstlenir. Sunucuları, channel'ları (topic'ler), operation'ları ve mesaj payload'larını YAML veya JSON olarak, Kafka'ya özgü binding'lerle tanımlar.

Kafka API'lerini belgelemek için bir schema registry'e ihtiyacım var mı?

Hayır, ama yardımcı olur. Dokümanlar kuralları belirtir; bir registry bunları yazma zamanında uygular. Bir registry kullanıyorsanız, uyumluluk modunu belgeleyin.

Bir Kafka topic'ini belgelemekle bir REST endpoint'ini belgelemek arasındaki fark nedir?

REST dokümanı bir istek ve yanıtı tanımlar. Kafka dokümanı ise daha sonra birçok consumer'ın okuyacağı tek bir mesajı tanımlar, bu yüzden ayrıca anahtarı, sıralama kapsamını, teslimat garantisini, saklama süresini ve consumer group'ları da içermelidir. Bunların hiçbiri tipik bir REST dokümanında yer almaz.

Apidog Kafka mesajlarını test edebilir mi?

Apidog, Kafka endpoint'lerini Custom Protocol API üzerinden belgeler, ancak Kafka mesajı göndermez veya tüketmez. Sözleşmeyi ve payload şemalarını tutmak için kullanın ve producer ile consumer kodunu Kafka client kütüphanenizle test edin.

Kafka dokümantasyonunu ne sıklıkla güncellemeliyim?

Bir producer mesajı her değiştirdiğinde. Bunu kod incelemesine bağlayın: event'i değiştiren pull request sözleşmeyi günceller ya da ajanınız onu Apidog CLI ile yeniden oluşturur.

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin