AsyncAPI

A team designing customer-profile and transaction topics must agree on more than topic names: partition counts, message keys, and event structures also affect how services use those topics. AsyncAPI provides a version-controlled specification for documenting these event-driven interactions. Unlike a general-purpose wiki page, its YAML or JSON files can travel with project changes in a repository. section 2.2.4 section 2.4.2

AsyncAPI describes communication through channels, messages, and operations without requiring one messaging implementation. A channel is a logical address; for Kafka, its address is a topic name. Kafka bindings add implementation-specific properties such as partition counts. section 2.2.4

asyncapi: 3.0.0
info:
  title: Customer 360 Project
  version: 1.0.0
  description: >
    This project aims to aggregate data from various sources, providing a
    comprehensive view of customer information.

channels:
  customerProfile:    #1
    description: Storing profile information of customers.
    address: CUSTOMER_PROFILES   #2
    bindings:    #3
      kafka:
        partitions: 9    #4
  transactions:
    description: Information about customer transactions.
    address: TRANSACTIONS
    bindings:
      kafka:
        partitions: 9

The Customer 360 specification gives two channels business descriptions and Kafka topic addresses, then records nine partitions for each topic. section 2.2.4

Channel documentation can also describe messages. Kafka-specific message keys belong in bindings: a customer ID keeps profile updates ordered per customer, while a transaction ID helps distribute transactions across partitions. Recording message structure gives producing and consuming teams an agreed format, even though Kafka does not enforce that structure. section 2.4.2

There are two approaches to event structure:

• Define it in AsyncAPI for a self-contained, reusable abstract model. section 6.3.5
• Define an Avro schema separately and reference it from AsyncAPI. This keeps the concrete schema in a developer-facing format and avoids potential translation gaps and constraint limitations in the abstract model. section 6.3.5

asyncapi: 3.0.0
info:
  title: Customer 360 Project
  version: 1.0.0
  description: >
    This project aims to aggregate data from various sources, providing a 
    comprehensive view of customer information.

channels:
  customerProfile:
    description: Storing and distributing profile information of customers.
    address: CUSTOMER_PROFILES 
    messages:
      userProfile:
        payload:
          schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
          schema:
            $ref: './path/to/submodule/path/to/UserProfile.avsc'

The customer-profile message points to an external Avro schema, illustrating how topic documentation and a separately maintained event schema can remain connected. section 6.3.5

Use the specification as a shared record of decisions, not as a substitute for making them. Once a Kafka use case is chosen, topic requirements can include business-event references, producers, consumers, naming, replication, partitions, and retention. Keeping these definitions aligned supports consistent management of the cluster as the project grows. section 10.1.3 section 10.2