asyncapi-intro.md

What is AsyncAPI?

• specification for describing application's API
• machine-readable YAML and JSON -> Check in the Studio
• very similar to OpenAPI

What is AsyncAPI Initiative?

• Linux Foundation project -> Charter
• Open governance -> Anyone can join Technical Steering Committee
• Specification and tools

What are specification key concepts?

Basic

• AsyncAPI is for describing the application interface, not the broker
• EDA is not broker only, thus AsyncAPI is not only for broker-centric architectures
• Channels are topics
• Publish/subscribe operations

Flexibility

• Protocol agnostic aka bindings feature. Like with MQTT when you connect to it, clientId must be provieded
• Multiple message schema formats (schemaFormat) aka "Just reuse what you already have defined in other systems" -> AsyncAPI Schema, JSON Schema, OpenAPI, RAML DT, Avro

  //example message data - GOOD
  {
    "displayName": "Shrek from the swamp",
    "email": "shrek@swamp.com",
    "age": 39
  }
  //example message data - BAD
  {
    "displayName": "Shrek from the swamp",
    "email": "shrek@swamp.com",
    "age": "39y"
  }
  

  //json schema
  {
    "description" : "User information",
    "type" : "object",
    "additionalProperties": false,
    "properties" : {
      "displayName" : {
        "type" : "string"
      },
      "email" : {
        "type" : "string"
      },
      "age" : {
        "type" : "integer",
      }
   }
  }   
  

  //asyncapi schema
  {
    "description" : "**User** information",
    "type" : "object",
    "additionalProperties": false,
    "properties" : {
      "displayName" : {
        "type" : "string"
      },
      "email" : {
        "type" : "string"
      },
      "age" : {
        "type" : "integer",
      }
   }
  }   
  

  //avro
  {
    "type": "record",
    "name": "User",
    "namespace": "com.company",
    "doc": "User information",
    "fields": [
      {
        "name": "displayName",
        "type": "string"
      },
      {
        "name": "email",
        "type": "string"
      },
      {
        "name": "age",
        "type": "int"
      }
    ]
  }
  

• Extensibility through x- properties. Useful when there is something not available in the spec, like specifying a response

Info structure optimization

• Traits for common info inside AsyncAPI document. Like with this Kafka example
• Sharing of information between components and files with JSON References($ref) as in this social media example