Managing the Next Generation of API Specifications

AsyncAPI is an API specification for defining event-driven architecture. The AsyncAPI Initiative provides the machine-readable specification, core tooling, as well as community tooling for defining the diverse set of APIs that are needed across this enterprise. Shortly after Swagger was put into the OpenAPI Initiative in 2015, being reborn as OpenAPI, AsyncAPI was created as a companion specification to meet the needs of event-driven APIs.

In December of 2020, Postman decided to further support AsyncAPI. It’s nearly a year later, and now we want to take a moment to not only highlight the work going on around the specification, but also the creative and unique ways in which the AsyncAPI team is managing what we see as the next generation of API specifications.

Event-driven architecture

There are many different architectural patterns in use across the API space, and one of the more progressive patterns gaining traction is known as event-driven architecture: an approach to designing and operating APIs using events to trigger and communicate between many different services. Event-driven architecture is not a new concept but has been getting significant traction in the last decade, helping to manage the complexity that exists across the hundreds or thousands of microservices that have emerged across internal operations.

Starting with the basics

To understand the potential of AsyncAPI for not just the world of APIs but also the applications they power, it helps to have a basic understanding of what it is and what it does. Don’t worry, I won’t make you write any code for this, but I will ask that you look at some YAML to understand a few of the fundamental building blocks of AsycAPI and event-driven architecture. Every AsyncAPI document begins with an information block that tells us the name of the API and describes what the API does.

asyncapi: '2.2.0'
info:
 title: Account Service
 version: 1.0.0
 description: This service is in charge of processing user signups

Now that we know what the API does, we can define which channels we are able to subscribe to. In this case, we are doing a basic account API that allows us to subscribe to any user signup that occurs. AsyncAPI allows us to define this basic channel API definition for our API using YAML.

channels:
 user/signedup:
    subscribe:
      message:
        $ref: '#/components/messages/UserSignedUp'

Next, all we need is a description of the message payload to expect when subscribed to our user/signedup channel. Producing this YAML to describe the displayName and email of the user who is signing up triggers a new event we can subscribe to across many different applications.

components:
 messages:
    UserSignedUp:
      payload:
        type: object
        properties:
          displayName:
            type: string
            description: Name of the user
          email:
            type: string
            format: email
            description: Email of the user

This provides a very simple look at the basics of what AsyncAPI does, employing a common everyday example of event-driven architecture. However, this story isn’t just about AsyncAPI; it’s about the process used to manage the specification that makes it so unique, and looking at it as an example of how to support the future of API specifications.

7 things to successfully manage a specification

To understand why AsyncAPI is unique, let’s start with the expected basics of managing the specification, but then quickly expand into some of the other pretty special and effective ways the AsyncAPI community has been contributing to its exponential growth and adoption today.

1. Front-door website for easy access

The AsyncAPI team started with the basics really well, providing a simple modern website that tells everything about what they do. The website is active and puts everything around the specification within reach as soon as you land on the home page. The AsyncAPI website provides access to what anyone in the community needs to begin learning about the API specification, how to put it to work, and even how to begin contributing to the specification. It provides the jumping-off point for a very sophisticated approach to managing the API specification that is redefining the enterprise API toolbox.

2. Management of the core specification

AsyncAPI is managed via Github, with one of the most well-done organization pages I have come across in my time working with APIs. Their GitHub organization page provides access to the repo used to manage the specification, what you need to join the community, and how to contribute to the specification and tools. AsyncAPI makes sure that the technical steering committee (TSC) for the specification is transparent and accessible to the community, and that the road map for the specification is front and center to help guide the TSC and the community forward. AsyncAPI’s usage of Github reflects many other specifications you come across, except for the organizational landing page, which is a pretty shining example of a first impression that you can make within any community. Laying a solid but open foundation for how you manage the next generation of APIs.

3. Core AsyncAPI Tooling

The AsyncAPI specification is important in the central role it plays, but the specification means nothing without the support of its core and community tooling. Most people involved in API operations will not care about the specification, but they will care about the value generated by tooling. Here are a handful of open source tools at the heart of the AsyncAPI ecosystem that provides the conveyor belts and gears of any modern API factory floor:

• Parser: Parses any version of the specification.
• Generator: Generates code, documentation, and pretty much anything you can imagine by leveraging its templating system.
• Studio: A visual studio for working with the specification.
• Glee: A specification-first framework that makes it really easy to build APIs.
• Modelina: A modeling solution for working with the specification.
• Event Gateway: A gateway for managing events.
• CLI: A command-line interface for working with the specification.

These are just seven of the core tools that are available to support AsyncAPI across the API lifecycle. There are other tools developed by the AsyncAPI team and the wider community, but these core tools are essential in helping make adopting the specification easier to put it to use and keep up with each version change in the future. These core tools lay the foundation for applying AsyncAPI across the API lifecycle and API operations. Furthermore, how people use and respond to these tools helps move the API specification forward as it evolves based on the needs of those putting it to work.

4. Community feedback loop

When it comes to constructing an effective feedback loop for the community, the AsyncAPI team fires on all cylinders. Along with the fundamentals of having active Twitter and LinkedIn profiles, there is also the AsyncAPI blog (complete with RSS feed), and they welcome story submissions via Github. If you are looking for more real-time engagement, you can join the AsyncAPI Slack channel, or jump in on the discussions occurring on the AsyncAPI Github community repository. To step up community participation around AsyncAPI, there are regular meetings anyone can participate in. You can get plugged in via the mailing list, add their calendar, or just watch the meetings after they have happened via the Youtube playlist. It may not seem like it at first glance, but this represents a very sophisticated way of constructing a feedback loop around an open source specification and tooling, ensuring information is coherently and constructively broadcasted out to the community. But most importantly, this ensures the community has ways to make sure their voice is heard.

5. Accessible conversations

One thing that the AsyncAPI team excels at is turning everything that happens in the community into a video experience that anyone can tune into. On the AsyncAPI Youtube channel and Twitch, you can find a steady stream of video content: there are their regular meetings, the Thinking Out Loud series in which they work through the biggest problems in the community, their Contributor-First series that helps onboard contributors to the spec and tooling, team livestreams, and much, much more. The regular drumbeat of informative and often entertaining video content is amplified via the community social media channels and the feedback loop—keeping everyone informed. The AsyncAPI team really gets what is needed to help make learning and contributing to the specification and tooling an ongoing learning experience, all while bringing in new people to the discussion and engaging with community veterans.

6. Annual conference

In addition to the regular drumbeat of virtual meetings and discussions, AsyncAPI holds an annual conference which they plan out entirely in the open on Github. You can find discussions dedicated to marketing, sponsors, swag, and event budget, as well as find the videos after the fact on Youtube. The AsyncAPI conference reflects the radically open attitude of the AsyncAPI team and community. They make sure that everyone is part of the conversation, and all the details of putting the event together are made publicly available. This approach acknowledges that transparent conversations are essential to the future of the specification. The conference is also very intentional about bringing together a diverse range of voices to talk about the specification, tooling, and why it matters in their API operations and businesses.

7. Business support of an API specification

The last layer of the AsyncAPI community I will showcase as part of this story is the business side of moving an open source specification forward, understanding that it takes money to actually move many of these open source conversations forward. Anyone can support AsyncAPI through their Open Collective profile, supporting either the specification or the conference, or even both! They do a good job of showcasing their sponsors on Github and the website, making sure that everyone knows who is helping support the community. If you aren’t quite ready to sponsor, you can also acquire merchandise, which will financially help the community but also allow you to show your support by wearing AsyncAPI online and out in the real world. AsyncAPI is part of the Linux Foundation, which provides a strong base of support for the project, and the core AsyncAPI team is employed as part of Postman Open Technologies. But the project still needs wider community support to operate, so please take the time to support in any way you can.

AsyncAPI and radical transparency

It is important for AsyncAPI to exist today, but it is vital that the specification evolves based upon contributions from the entire community—all to produce the most meaningful and useful specification possible. The AsyncAPI team has opted for a radical level of transparency in that they share almost everything out in the open for the community to learn from. Anyone can join in on the Slack channel, and almost every aspect of the project is operated out in the open via Github repositories. This is where AsyncAPI really stands out, in that they feel that the process and budget for the community, events, and specification should be completely transparent. They also feel strongly that the core tooling—like generator, parser, documentation, and studio—all act as an important governor for guiding the specification forward, and they help reduce friction for tooling and service providers when it comes to supporting future versions of the specification.

Managing an API specification into the future

Open source API specifications like OpenAPI, AsyncAPI, and JSON Schema are essential for us all to standardize, automate, and govern our APIs at scale. I’ve walked you through the AsyncAPI community in hopes of getting you more involved in what is happening, while also showcasing the work Postman is doing to help support AsyncAPI. This is an important blueprint for how open source API specifications can be managed successfully. And we are using this as a blueprint for stabilizing and growing the JSON Schema community, as well as finding ways we can further influence the OpenAPI community.

The AsyncAPI team’s passionate belief in transparency, the importance of core tooling, and a sophisticated feedback loop across the AsyncAPI community are making AsyncAPI the go-to specification for today’s diverse API toolbox. We can look to their approach as the way forward into the future when it comes to managing any open source API specification.