Specyfikacja AsyncAPI to plik YAML lub JSON opisujący kilka kluczowych sekcji: info (metadane API), servers (brokery wiadomości), channels (topics, queues lub inne punkty wymiany), operations (akcje send/receive), messages (definicje payloadów) oraz components (reużywalne schematy, security, parametry). W wersji 3.0 operations są jednostką pierwszej klasy, oddzieloną od channels, co ułatwia opis bardziej złożonych przepływów i reużycie kanałów między operacjami. Tooling czyta specyfikację i generuje dokumentację HTML, klienty i serwery w językach takich jak Java, TypeScript, Go i Python oraz validatory payloadów wykorzystywane w runtime'ie i testach kontraktowych.
Przed AsyncAPI nie istniał uznany standard opisywania asynchronicznych API. OpenAPI pokrywa świat REST, ale nie nadaje się do messagingu i streamów zdarzeń. Bez wspólnego kontraktu integracje event-driven były robione ad-hoc, dokumentacja szybko desynchronizowała się z kodem, a generowanie klientów i serwerów było praktycznie niemożliwe. AsyncAPI dostarcza maszynowo-czytelny kontrakt, który eliminuje te luki i pozwala traktować systemy event-driven na równi z synchronicznymi API.
Pojedynczy plik YAML lub JSON zawierający kompletną specyfikację API event-driven.
Logiczne punkty wymiany wiadomości — topics w Kafka, queues w AMQP, paths w WebSocket.
Akcje send i receive opisujące co aplikacja robi z kanałem. W 3.0 oddzielone od channels.
Definicje payloadów zdarzeń wraz ze schematem (JSON Schema, Avro, Protobuf), nagłówkami i przykładami.
Konfiguracja specyficzna dla protokołu — np. partition key dla Kafka, exchange type dla AMQP, QoS dla MQTT.
Oficjalna
AsyncAPI 3.0 wprowadza fundamentalne zmiany strukturalne (rozdzielenie operations od channels), przez co dokumenty 2.x nie są bezpośrednio kompatybilne z toolingiem 3.x.
Bez automatycznej walidacji specyfikacja szybko rozjeżdża się z faktycznymi payloadami publikowanymi przez producentów.
Bindings (np. dla Kafka czy AMQP) bywają wypełniane częściowo lub błędnie, co prowadzi do nieprawidłowo wygenerowanych klientów i serwerów.
Fran Méndez publikuje pierwszą wersję specyfikacji jako open-source — odpowiednik OpenAPI dla messagingu.
Projekt przechodzi pod Linux Foundation, zyskując neutralne zarządzanie i przyspieszoną adopcję.
Znaczące zmiany strukturalne specyfikacji oraz rozbudowa systemu bindings dla różnych protokołów.
Operations stają się jednostką pierwszej klasy, niezależną od channels, co umożliwia bogatsze opisy przepływów.
AsyncAPI staje się standardem opisu zdarzeń dla agentów LLM i systemów multi-agent w pipeline'ach AI.
Wybór protokołu transportu: Kafka, AMQP, MQTT, WebSockets, NATS, JMS, STOMP, Redis, IBM MQ.
Wersja AsyncAPI: 2.x vs 3.x. W 3.x operations są rozdzielone od channels, co zmienia strukturę dokumentu.
Format schematu payloadu: JSON Schema, Avro lub Protobuf.
AsyncAPI jest specyfikacją (kontrakt YAML/JSON), nie runtime'em — nie wykonuje obliczeń ani nie jest związane z konkretnym sprzętem.
