A presentation at Nordic Kafka Meetup by Lorna Jane Mitchell
Introduction to AsyncAPI for Kafka Lorna Mitchell, Aiven
Introducing: AsyncAPI Specification for describing event-driven and data streaming systems. • https://asyncapi.com • Open standard • Active community • Supports Kafka! And MQTT, AMQP, WS …. @lornajane
Why use AsyncAPI? Describe your event-driven systems in a useful and reusable way. • Clearly track changes in a text-based description • Generate documentation and code • Verify system operations against description • Enclose existing payload descriptions (CloudEvents, Avro) within AsyncAPI @lornajane
Bunch of JSON/YAML asyncapi: ‘2.0.0’ id: ‘urn:com.github.lornajane.example1’ info: contact: license: servers: local-kafka: channels: factorysensor: subscribe: message: payload: examples: components: securitySchemes: messages: @lornajane
Generated Docs @lornajane
AsyncAPI Descriptions
AsyncAPI Structure Top-level elements: • asyncapi and id • info • servers • channels • tags • components @lornajane
Info Section Valuable metadata is held in info. info: title: Thingum Industries Sensors description: Keeping the factory and all the machines running nicely version: 1.0.0 contact: name: Lorna email: lornajane@aiven.io url: https://github.com/aiven/thingum-industries license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html @lornajane
Channels Section Main operations are described here channels: door-sensor: description: Door sensors (external and internal) subscribe: operationId: DoorSensor description: Open/closed state information from the doors. tags: - name: sensor bindings: kafka: clientId: type: string message: $ref: ‘#/components/messages/DoorData’ @lornajane
$ref Reusable Content Refer to content in the components section message: $ref: ‘#/components/messages/DoorData’ Useful for reuse and readability. We can also refer to other files: message: $ref: ‘doors-publish.yaml#/components/messages/DoorData’ @lornajane
Components Section A collection of reusable components components: messages: DoorData: name: door-sensor-data title: Door Sensor Reading description: Door sensor data payload: type: object properties: location: type: string state: enum: [“open”, “closed”] @lornajane
AsyncAPI Loves Standards AsyncAPI is compatible with other standards: • Avro or CloudEvent payload descriptions can be accessed with $ref • JSONSchema is supported • Based on and builds on OpenAPI @lornajane
AsyncAPI Tools
Generate Documentation Documentation with https://www.asyncapi.com/generator @lornajane
Generate Code Also using the generator: ag thingum/doors-publish.yaml \ @asyncapi/nodejs-template \ -o thingum/nodejs \ -p server=development @lornajane
Tools Landscape • VSCode extension: https://github.com/asyncapi/vs-asyncapi-preview • Validation/linting: https://stoplight.io/open-source/spectral/ • Generate test data: https://microcks.io/ • GitHub action: https://github.com/WaleedAshraf/asyncapi-github-action @lornajane
AsyncAPI and You Open standards, seamless integrations
Resources • AsyncAPI: https://asyncapi.com • Aiven: https://aiven.io - try the free trial • Examples: https://github.com/aiven/thingum-industries @lornajane
Kafka is such a powerful and flexible way of streaming events and data, and can accommodate an unending variety of data types and structures, in a variety of formats. This great feature can also be a bug when you’re integrating with yet another completely different stream of data!
Enter AsyncAPI, an open standard for describing records in event-driven systems. Using AsyncAPI you can clearly describe the data payloads and transform that information into developer-friendly documentation; other tools can validate AsyncAPI and generate code for clients or integrations. In this session you will see “behind the curtain” of how the AsyncAPI document is structured, and get a demo of some of the tools that build on AsyncAPI to build things like documentation and example code. If you aren’t using AsyncAPI already, and your Kafka talks to other systems, then you’ll want to see this talk.
