AsyncAPI Primer

1.Why AsyncAPI matters

REST contracts describe request/response cycles, but most modern backends also speak websockets, Kafka, MQTT, or AMQP. AsyncAPI gives those channels the same kind of typed, versioned, generator-friendly spec that REST has enjoyed for years. One YAML file unlocks SDKs, mock servers, and docs.

For Meridian customers shipping live dashboards or agent fan-outs, an AsyncAPI spec is the contract that keeps producers and consumers aligned.

2.A minimal 3.0 document

The shape below declares a single websocket channel that emits aUserSignedUpevent. Note that 3.0 splits channels from operations so the same channel can be both produced and consumed by different parties.

asyncapi: 3.0.0
info:
  title: Meridian Events API
  version: 1.0.0
  description: Real-time event streams for Meridian platform
servers:
  production:
    host: events.meridian.dev
    protocol: wss
channels:
  userSignedUp:
    address: 'user/signed-up'
    messages:
      UserSignedUp:
        payload:
          type: object
          properties:
            userId:
              type: string
            email:
              type: string
            timestamp:
              type: string
              format: date-time
operations:
  onUserSignedUp:
    action: receive
    channel:
      $ref: '#/channels/userSignedUp'

3.Generating clients

Once the spec is in source control, the AsyncAPI generator can emit TypeScript, Python, or Go clients on every push. Meridian recommends pinning the generator version in CI and committing the produced SDK to a sibling repo so consumers can install it like any other package.

Pair that with a contract-test step that lints the spec against the broker's schema registry, and breaking changes get caught before they ship.