The idealized world of AsyncAPI is neat and tidy:

  • Interface definitions show developers exactly what events are exchanged amongst producers and consumers.
  • Event contracts only change when permitted by well-defined governance processes.
  • Bindings fill in the implementation details for open-source brokers like Kafka (including Confluent) and RabbitMQ along with closed-source brokers like IBM MQ and Solace.

The real world is often messier. In the decades-long absence of an asynchronous API spec, teams adopted (or didn’t adopt, or chose to ignore) different API definitions and governance. The result is a twisted mess of event producers, consumers, data paths, and multiple broker technologies, from on-premises to cloud connections.

Oftentimes, removing an event topic or queue requires nerves of steel, for fear it might disrupt key functionality. Many a middleware engineer has found religion during a production broker clean-up.

Thankfully, the AsyncAPI Discovery Tool offers a better way.

How the AsyncAPI Discovery Tool Works

The AsyncAPI Discovery Tool analyzes event traffic passing through brokers like Kafka, RabbitMQ, IBM MQ, Solace, and more. After learning how the broker distributes events, the AsyncAPI Discovery Tool generates a corresponding AsyncAPI specification. The generated spec can be used for code generation, documentation, visualization, infrastructure deployment, and more.

AsyncAPI vs. OpenAPIAnswers to common questions about AsyncAPI vs OpenAPI, including what APIs are, how they began, and what the future holds for API spec.Read moreSolly logo

It’s a great starting point for getting events catalogued and governed.

It’s not perfect (more on that later), and there’s a lot more work to be done, but the AsyncAPI Discovery Tool helps your enterprise align production reality with AsyncAPI documentation. And perhaps relieve some tension for middleware engineers.

Getting Started with AsyncAPI Discovery

Getting started means a trip to the SolaceLabs GitHub, where you can find detailed instructions and documentation. (While Solace created AsyncAPI Discovery, it’s open source with an Apache 2.0 license.)

The AsyncAPI Discovery Tool runs as a stand-alone Java Jar, so getting it running requires only Java and Maven. Once it’s up and running, AsyncAPI has its own self-contained UI, offering fill-in-the-blanks configuration (get more details about the UI). Here’s an example for Kafka:

Screenshot of AsyncAPI Discovery Tool for Kafka

Figure 1: UI for AsyncAPI Discovery for Kafka

Just fill in the configuration, asking your friendly local administrator for help if needed, and then click the “Start Scan” button. After grinding away, the AsyncAPI Discovery Tool returns a consolidated spec file. The AsyncAPI file describes the channels and schemas of events passing through the broker. From there, the world is your oyster: generate code, create infrastructure, or start governing your events.

asyncapi specification from asyncapi discovery tool

Figure 2: Resulting (greatly simplified) AsyncAPI spec

Alternatively, power users or those looking to integrate AsyncAPI with other tools should also know that there is a REST API available. This can serve as a great way to audit your infrastructure to detect unauthorized changes, or to confirm that deployments went according to plan.

The Future of the AsyncAPI Discovery Tool

The most obvious place to improve the AsyncAPI Discovery Tool is to expand the number of supported brokers. Right now, it supports:

  • Apache Kafka
  • Solace PubSub+
  • NATS
  • RabbitMQ
  • HiveMQ

Fortunately, it was built with extensibility in mind. There is a documented plug-in architecture just itching to have more brokers added. If you’re interested, The people who maintain the tool welcome pull requests.

Additionally, it also runs into some of the same issues that confront AsyncAPI more generally, like:

  • The confusing publish and subscribe verbs in the output.
  • The requirement that a single file must represent a single application makes it tough to get a high-level understanding of the architecture.

As the spec matures, the tooling will hopefully be close behind.

Conclusion

In the meantime, the AsyncAPI Discovery Tool can be a huge help to enterprises that are new to AsyncAPI but experienced with event-driven architecture and messaging. The AsyncAPI Discovery Tool can start you down the road from a tangled event mess, to a well-organized, fully documented, tightly governed architecture.

Array ( [117] => Array ( [name] => Jesse Menning [picture] => [bio] =>

As an architect in Solace’s Office of the CTO, Jesse helps organizations of all kinds design integration systems that take advantage of event-driven architecture and microservices to deliver amazing performance, robustness, and scalability. Prior to his tenure with Solace, Jesse was an independent consultant who helped companies design application infrastructure and middleware systems around IBM products like MQ, WebSphere, DataPower Gateway, Application Connect Enterprise and Transformation Extender.

Jesse holds a BA from Hope College and a masters from the University of Michigan, and has achieved certification with both Boomi and Mulesoft technologies. When he’s not designing the fastest, most robust, most scalable enterprise computing systems in the world, Jesse enjoys playing hockey, skiing and swimming.

[position] => [url] => https://solace.com/blog/author/jessemenning/ ) )
Jesse Menning

As an architect in Solace’s Office of the CTO, Jesse helps organizations of all kinds design integration systems that take advantage of event-driven architecture and microservices to deliver amazing performance, robustness, and scalability. Prior to his tenure with Solace, Jesse was an independent consultant who helped companies design application infrastructure and middleware systems around IBM products like MQ, WebSphere, DataPower Gateway, Application Connect Enterprise and Transformation Extender.

Jesse holds a BA from Hope College and a masters from the University of Michigan, and has achieved certification with both Boomi and Mulesoft technologies. When he’s not designing the fastest, most robust, most scalable enterprise computing systems in the world, Jesse enjoys playing hockey, skiing and swimming.

What's New with PubSub+? Find out on December 7!