Apache Kafka

asyncapi: 2.6.0
info:
  title: Apache Kafka
  version: '1.0.0'
  description: >-
    Generic AsyncAPI 2.6 reference template for Apache Kafka. Apache Kafka is
    a distributed event streaming platform where producers publish records to
    topics partitioned across a cluster of brokers, and consumers organized
    into consumer groups subscribe to those topics. This template models the
    Kafka wire protocol using the AsyncAPI kafka and kafka-secure bindings
    and is intended to be customized for a specific cluster, topic set, and
    message schemas. It is not tied to any single Kafka deployment.
  contact:
    name: Apache Kafka
    url: https://kafka.apache.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  tags:
    - name: kafka
    - name: event-streaming
    - name: pub-sub
defaultContentType: application/json
servers:
  kafka-secure:
    url: '{broker}:9092'
    protocol: kafka-secure
    description: >-
      Apache Kafka broker endpoint exposed over TLS with SASL/SCRAM
      authentication. Replace {broker} with the hostname or bootstrap host
      of a broker in the target cluster. Clients should be configured with
      the full bootstrap.servers list rather than relying on a single host.
    protocolVersion: '3.0'
    variables:
      broker:
        description: >-
          Hostname of a Kafka broker (advertised listener) or bootstrap
          host. In practice, clients pass a comma-separated bootstrap.servers
          list and the cluster returns the full broker set in metadata.
        default: kafka.example.com
    security:
      - saslScram: []
  kafka-secure-mtls:
    url: '{broker}:9093'
    protocol: kafka-secure
    description: >-
      Apache Kafka broker endpoint exposed over TLS with mutual TLS (mTLS)
      client certificate authentication. Use this variant when the cluster
      is configured with the SSL security protocol and ssl.client.auth set
      to required.
    protocolVersion: '3.0'
    variables:
      broker:
        description: Hostname of a Kafka broker advertised listener.
        default: kafka.example.com
    security:
      - mtls: []
channels:
  '{topic}':
    description: >-
      Generic Kafka topic template. A Kafka topic is an append-only,
      partitioned, replicated log of records. Producers append records to
      partitions and consumers read records in offset order within each
      partition. Replace {topic} with the concrete topic name.
    parameters:
      topic:
        description: >-
          The Kafka topic name. Topic names are case-sensitive and may
          contain ASCII alphanumerics, '.', '_' and '-'. Maximum length is
          249 characters.
        schema:
          type: string
          maxLength: 249
          pattern: '^[a-zA-Z0-9._-]+$'
    bindings:
      kafka:
        topic: '{topic}'
        partitions: 3
        replicas: 3
        topicConfiguration:
          cleanup.policy:
            - delete
          retention.ms: 604800000
          retention.bytes: -1
          delete.retention.ms: 86400000
          max.message.bytes: 1048588
        bindingVersion: '0.5.0'
    publish:
      operationId: produceToTopic
      summary: Produce a record to a Kafka topic
      description: >-
        Publish a record to the topic. The producer client determines the
        target partition either by an explicit partition number, by hashing
        the record key, or by the configured partitioner. Records within
        a single partition are strictly ordered.
      bindings:
        kafka:
          clientId:
            type: string
            description: >-
              The client.id producer configuration sent with every request
              to the broker. Used by the broker for logging, metrics, and
              quota enforcement.
          bindingVersion: '0.5.0'
      message:
        $ref: '#/components/messages/KafkaRecord'
    subscribe:
      operationId: consumeFromTopic
      summary: Consume records from a Kafka topic
      description: >-
        Subscribe to the topic as part of a consumer group. The group
        coordinator assigns partitions to the consumers in the group and
        tracks committed offsets per (group, topic, partition). Each
        partition is consumed by at most one member of a given consumer
        group at a time.
      bindings:
        kafka:
          groupId:
            type: string
            description: >-
              The group.id consumer configuration. All consumers sharing a
              group.id form a single logical subscriber; partitions of the
              topic are divided among the members of the group.
          clientId:
            type: string
            description: >-
              The client.id consumer configuration sent with every request
              to the broker. Used for logging, metrics, and quota
              enforcement.
          bindingVersion: '0.5.0'
      message:
        $ref: '#/components/messages/KafkaRecord'
components:
  messages:
    KafkaRecord:
      name: KafkaRecord
      title: Kafka Record
      summary: >-
        A single Kafka record (message) carried on a topic partition.
      description: >-
        A Kafka record is an immutable key/value pair with a timestamp and
        optional headers. Keys are typically used by producers to drive
        partition assignment via hash-based partitioning. Payloads can be
        any binary format; common encodings include Avro, Protobuf, and
        JSON Schema managed via Confluent Schema Registry, in which case
        the first byte of the payload is a magic byte and bytes 1-4 are
        the big-endian schema id (see Confluent wire format).
      contentType: application/json
      headers:
        type: object
        description: >-
          Kafka record headers. Each header is a key (UTF-8 string) and
          a value (byte array). Headers are commonly used for tracing
          context, content type, and idempotency keys.
        additionalProperties:
          type: string
      payload:
        $ref: '#/components/schemas/RecordPayload'
      bindings:
        kafka:
          key:
            type: string
            description: >-
              The Kafka record key. When set, the default partitioner
              hashes the key bytes to select a partition, giving all
              records with the same key the same partition and therefore
              a stable per-key order.
          schemaIdLocation: payload
          schemaIdPayloadEncoding: confluent
          schemaLookupStrategy: TopicIdStrategy
          bindingVersion: '0.5.0'
      examples:
        - name: avroRecord
          summary: >-
            A record encoded with Avro and registered in Confluent Schema
            Registry, using the default TopicNameStrategy.
          payload:
            id: 42
            event: example.created
            occurredAt: '2026-05-30T12:00:00Z'
  schemas:
    RecordPayload:
      type: object
      description: >-
        Generic record payload. Replace this schema with the concrete
        Avro, Protobuf, or JSON Schema definition for your topic.
      properties:
        id:
          type: string
          description: Domain identifier for the event.
        event:
          type: string
          description: Event type name.
        occurredAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp the event occurred.
        data:
          type: object
          additionalProperties: true
          description: Event-specific payload.
  messageTraits:
    AvroTrait:
      schemaFormat: application/vnd.apache.avro;version=1.9.0
      contentType: application/octet-stream
      bindings:
        kafka:
          schemaIdLocation: payload
          schemaIdPayloadEncoding: confluent
          schemaLookupStrategy: TopicIdStrategy
          bindingVersion: '0.5.0'
    ProtobufTrait:
      schemaFormat: application/vnd.google.protobuf;version=3
      contentType: application/octet-stream
      bindings:
        kafka:
          schemaIdLocation: payload
          schemaIdPayloadEncoding: confluent
          schemaLookupStrategy: TopicIdStrategy
          bindingVersion: '0.5.0'
    JsonSchemaTrait:
      schemaFormat: application/schema+json;version=draft-07
      contentType: application/json
      bindings:
        kafka:
          schemaIdLocation: payload
          schemaIdPayloadEncoding: confluent
          schemaLookupStrategy: TopicIdStrategy
          bindingVersion: '0.5.0'
  securitySchemes:
    saslScram:
      type: scramSha512
      description: >-
        SASL/SCRAM-SHA-512 authentication over a TLS-encrypted connection
        (security.protocol=SASL_SSL, sasl.mechanism=SCRAM-SHA-512). Use
        SCRAM-SHA-256 in environments that require it.
    saslPlain:
      type: plain
      description: >-
        SASL/PLAIN authentication over TLS (security.protocol=SASL_SSL,
        sasl.mechanism=PLAIN). Only use over TLS; PLAIN sends credentials
        in cleartext.
    mtls:
      type: X509
      description: >-
        Mutual TLS client certificate authentication
        (security.protocol=SSL, ssl.client.auth=required). The broker
        validates the client certificate against its truststore.