DEV Community: Jay Cormier

How Bump.sh works with… remote work?

Jay Cormier — Mon, 17 Jul 2023 13:13:24 +0000

Ever since a certain pandemic, remote work has become increasingly popular. It was enforced by lockdowns, adopted long-term by some teams, and criticized for allegedly hampering productivity. Lately, some companies have been reversing their approval of remote work. On the other hand, entire teams are advocating for it to become the norm.

Our version of remote work has its own unique story. Legend has it that our two founders, Anthony and Sébastien, climbed to the top of the tallest building in France and held iPads to the sky to be etched by lightning with the founding principles of what would become Bump.sh.

Predictably, that wasn't covered by the warranty.

The usual suspects

Our journey with remote work is a long story that began well before the pandemic. We have always had some portion of work-at-home (or elsewhere) in our previous professional experiences.
Occasionally, for awaiting for a plumber or a delivery (that you missed. with no notice. and the delivery person rang but looks like you weren't at home. too bad.).
Sometimes, a few days were spent working in peace, without the hustle and bustle of an open-space office.
Or every week, because you lived far from the office and only drop by occasionally.

Each in our own way, we gradually came to the conclusion that remote work is a natural way of working for us. It's aligned with how we view our work-life balance and our relationship with our team.

You are probably familiar with the reasons.

The ability to work from anywhere. Whether it's in the capital or in the remote countryside of Loire-Atlantique, an apartment or a cabin, or even if you want a change of scenery and decide to work astride a wild horse in Camargue.

The gained autonomy has an undeniable impact on our daily life and overall well-being. The freedom of remote work means we can take our dog for a morning walk, see our kids off to school, or make a homemade lunch.

Some of us take some time to go to the gym. Others would paint, play an instrument or fight a deadly threat hidden among the stars. Whatever. It's about having control over our day. We can seamlessly blend work and life without compromising on either.

Not being geographically confined also allows us to recruit talent, wherever they may be (including in Camargue). By removing the constraint of a physical location and mandatory presence, we avoid the risk of missing out on individuals who have chosen to live where they feel their best.

Our magic recipe

Upon your arrival at Bump.sh, you will be faced with a crucial choice. Seated behind a desk, dressed in a black leather coat, one of our co-founders will present you with a crucial decision. In their right hand, the option to work remotely from the comfort of your home. In their left hand, the opportunity to work in a coworking space, as you may crave social interactions and the company of others.

Once you have made your decision amidst breathless anticipation, they will explain that you can also mix it up occasionally. Nothing is set in stone.
The idea is to create the best working environment for us. It could be a dedicated room at home (some even have verandas for that purpose). Sometimes, the need arises to experience the adventures and dramatic twists of a coworking space once or twice a week (it's better than a telenovela).

To facilitate daily communication, we have implemented meetings with one significant constraint: almost no one likes meetings. We are constantly seeking the best formula for this format, but we have arrived at a result that is starting to please us.

There are two main teams at Bump.sh (Product, which includes our engineers, and GoToMarket) that have a weekly meeting to discuss current topics. Then, there is an All-hands meeting where a representative from each team presents a summary, providing everyone with an overview of where things stand and how everyone is progressing.

Of course, we needed effective means to compensate for the absence of the sacred Coffee Machine for informal discussions. To address this, we have a daily reminder and a voice chat lounge where we can exchange stories and share our current moods and experiences.

This is where the importance of using the right tools to stay up-to-date comes into sharp focus. You're familiar with the classics: a shared calendar, a few emails, a well-known professional chat tool that we won't mention just to add a few lines to this article without shame or remorse.

How do you indicate that you're open to a coffee chat with the rest of the team? A slot on a shared calendar? A specific status on that infamous tool-whose-name-we-won't-speak? An emoji? A dedicated channel?

Like many of you, we use Slack as our primary communication tool. We also tried Gather.town, but unfortunately, it didn't resonate with everyone. For a long time, our meetings took place on meet.coop, an open-source video conferencing solution. However, their announcement of discontinuing the service in the coming months pushed us towards new horizons (which we are still exploring).

Collaboration at Bump.sh revolves around well-known figures in the industry. Our internal knowledge base, project management, meeting notes, and article drafts find their place on Notion. The hottest designs in your area can be found on Figma. And our Engineering team works continuously (*wink*) with GitHub.
In fact, discussing our tools alone would warrant an article, but we wanted to give you a glimpse.

Of course, working remotely doesn't mean we live as reclusive hermits, in our cabins deep in the woods, munching on raw roots.

All it takes is to look up to see the signs: a planetary alignment, a constellation that shines a little brighter than the others, or even a meteor shower. These are the heralds of our famous and popular In Real Life (IRL) meetups.

Travelling across the country, we gather in secret locations to celebrate APIs and our joy of working together. These are days of jubilation where we work studiously and feast like never before, returning to our huts and leaving behind the most mysterious secrets about these gatherings.

To be more precise, every 3 months, we organize an IRL (In Real Life) gathering to make up for missed after-work events and lost time. We select a location that accommodates everyone, with each event held in a different place from the previous one. We set a date, rent a nice space where we can both work and have fun. Around that, we plan various activities, evenings, board games, a few bottles... and the rest becomes part of the story.

It can be that smooth, right?

But here's the thing, remote work sometimes feels a lot like real office work, the kind with the accounting department giving you side-eye at the coffee machine ever since they noticed that strange overconsumption of post-its in your department. Don't deny it, the numbers never lie, they know.

There will always be those moments of frustration when communication is challenging. Or a written message causes teeth to grind due to its borderline tone. Or you think that this issue could have been solved in two minutes if you could have just gotten up and showed your diagrams at the neighboring desk.

We also might miss inviting a colleague for a drink after work. Or having a chair race in the open-space office (don't do this, it's highly risky and generates a lot of paperwork for HR, we won't back you up).

But just as office work has its own challenges to overcome, we find ours much more comfortable to face. While working from home demands compartmentalization, discipline, trust (in oneself and in others), we still find ourselves in a healthy, comfortable, and caring environment.

One could commute, wait for the elevator, settle at their desk, and keep an eye on the clock to await that perfect timing when taking a break won't offend anyone. Or one could work from home, on their sofa under a blanket with a good cup of coffee/tea within reach.

But in the end, we all face the same situation: working together primarily means communicating with the tools we have. No one ever said it would be easy. But nothing stops you from making it more comfortable, inclusive, and warm for others and yourself.

That's what we strive for at Bump.sh. And we have no intention of giving up.

The Best API Documentation Tools for Dev Teams in 2023

Jay Cormier — Tue, 28 Mar 2023 08:37:11 +0000

by Alexander Yu

In software engineering, dev teams often dismiss documentation as tangential—secondary to product development and feature work. While code design and implementation is a top priority for most software engineers, creating good documentation should carry equal weight in the product development process.

In a nutshell, documentation is like a manual for your software: it tells users how to use your API. But in addition to the "how to," great API documentation also helps users derive maximum value from your software, ensuring they don’t miss important features or waste time misusing your API. So having good API documentation is crucial in helping your product establish a strong user base and retain users in the long term.

However, keeping your API documentation up-to-date can be difficult and tedious, especially if you have to manually edit it every time your API changes. Luckily, there's a wealth of API documentation tools out there to help simplify and automate doc generation.

This article will focus on a handful of the most popular ones: SwaggerUI, ReDoc, ReadMe, apiDoc, Postman, and Bump.sh. In our discussion of each tool, you'll consider factors such as features, ease of usage, current community support, and pricing to help you determine which one is best for your use case. If your end goal is to create and maintain excellent API documentation without too much hassle, read on to learn more about these tools.

Swagger UI

Swagger is a set of open source tools that help you design and build an API, which you define using an OpenAPI Specification (OAS). In particular, Swagger UI is a tool that takes your OAS and automatically generates documentation for your API in an interactive HTML page.

Above is an example of what Swagger UI can generate based on an OAS. This API models a pet store where users might expect to be able to do operations like add a pet to the store and retrieve details of a particular pet.

Here, a POST method for uploading an image of a pet is expanded. Swagger UI includes all the documentation details required to use the API: endpoints, available operations, parameters, responses, data types, descriptions, and even examples. Also, notice how easily users can test the API by clicking the Try it out button.

Because so many APIs are already built using the Swagger framework, it takes little to no effort to automate API documentation using Swagger UI. This makes it an ideal use case for APIs that you build using an OAS.

Why Choose Swagger UI?

Features: Provided you have an OAS, Swagger UI automatically generates a full HTML visualization of your API, complete with API documentation and built-in testing.
Ease of use: Swagger UI is suitable for developers of all skill levels. Everything generated by Swagger UI is taken from an OAS file, and there's no additional setup required beyond that. When your OAS changes, your Swagger UI documentation changes as well to automatically reflect your new API.
Community support: Swagger is open source and is one of the most popular tools for creating RESTful APIs. Because of this, Swagger UI has a huge user base, making it easy to get actively involved with the community.
Pricing: You can access all Swagger UI features for free. For development teams that want a hosted version, Swagger’s cloud version, called Swagger Hub starts at $75/month. Swagger Hub’s paid plans also include more integrations like GitLab, Bitbucket, and Azure DevOps.
Limitations: Swagger UI doesn't offer the best developer experience and is not SEO-friendly, if you need your documentation publicly published.

ReDoc

ReDoc is a tool that's similar to Swagger UI. It also takes an OAS and renders an interactive HTML page with full API documentation details; however, it has a notable difference.

In the above screenshot, we're looking at the same Swagger-based pet store API, specifically the same /pet/{petId}/uploadImage POST method as before. However, compared to Swagger UI, ReDoc arranges the page in a modern three-column format, where the left column is for navigation, the central panel contains documentation, and the right panel contains examples.

The three-column format is perhaps the most popular API documentation format today, used by many well-known companies like Twilio and Stripe. The three-column format allows developers to view API documentation in tandem with related code samples.

Why Choose ReDoc?

Features: ReDoc automatically generates interactive API documentation based on your OAS. It's very similar to Swagger UI, but the main difference is that ReDoc renders the documentation in a modern three-column format.
Ease of use: Like Swagger UI, ReDoc is very easy to use if you already have an OAS. Whenever you make updates to your API, ReDoc re-renders automatically, so there's no need to make manual edits to your documentation.
Community support: ReDoc is an open source tool with a large customer base, along with extensive documentation and tutorials to help you answer questions.
Pricing: ReDoc is Redocly's community-edition product that's free to use. You can get more features on paid plans, for example, Redocly’s Basic tier ($69/month) lets you create public documentation and add multiple users, while the Professional tier ($300/month) allows you to remove their branding and get an integrated developer portal.
Limitations: The documentation drift problem exists for ReDoc, and it’s not as easy to customize as some options on this list. That said, their vendor extensions allow for much more customization than in SwaggerUI does.

ReadMe

ReadMe is a tool that offers a little more in terms of customization compared to Swagger UI and ReDoc. By default, it also generates a hub that contains all your API documentation in a three-column layout.

The above is taken directly from ReadMe's documentation. You can clearly see the details of a particular GET API, along with code samples and a Try it! button in the right column for testing.

ReadMe supports reading an OAS out-of-the-box for quick adoption. But what makes ReadMe stand out is that it allows for more customization in developing your documentation hub. In particular, you can add custom guides and tutorials, which is great if your APIs are designed to be used together. In addition, ReadMe has built-in monitoring features that allow you to track usage metrics for your APIs.

Why Choose ReadMe?

Features: ReadMe generates an API documentation hub based on an OAS or via a manual API editor. It also supports various customization features and ways to monitor your APIs.
Ease of use: Since ReadMe has the option of uploading an OAS, it's still very easy to get started with. However, it also caters to more advanced users or those looking to write custom guides and tutorials in addition to the base API reference.
Community support: ReadMe has a wide customer base, including companies like Clover and UiPath. There are also discussion forums that you can use to pose questions to the community.
Pricing: ReadMe's Free tier is good for getting started with your API reference and metrics. To customize your guide, you'll need to upgrade to at least the Startup tier ($99/month) or above.
Limitations: ReadMe’s new editor doesn’t allow for as many formatting options as some other tools, and while you can write guides and tutorials in the platform, it doesn’t allow you to upload project files to the portal.

apiDoc

Compared to the first three tools, apiDoc takes a different approach towards generating documentation. Rather than rely on an API definition file like OAS, apiDoc is a package that allows you to add documentation directly into your source code through annotations. While there are third-party libraries that can create OAS files based on code annotations, having this built-in makes apiDoc slightly better if you want to control documentation through code instead of having a separate tool.

The screenshot above shows a typical apiDoc page (here's the live demo) displaying details for a POST method. Content on this page is generated according to annotations in your source code: for example, the list of query parameters are generated through @apiParam tags in your code. This allows you to keep your internal documentation (geared towards developers working on the codebase) and external documentation (geared towards your users) in sync.

Why Choose apiDoc?

Features: apiDoc generates documentation based on content that you include in apiDoc annotations directly in your source code.
Ease of use: Setting up apiDoc is easy, but it does require you to become somewhat familiar with apiDoc's capabilities before you can use it to its maximum potential. In addition, updating the documentation may require a deployment since your docs are embedded with your source code.
Community support: apiDoc has a relatively smaller user base, but it's still used by over eleven thousand developers according to GitHub.
Pricing: apiDoc is absolutely free to use!
Limitations: Because apiDoc doesn't follow a community-led API specification, it’s harder to migrate to and from it. This also adds to the learning curve as you’ll have to make sure you know their rules for annotations.

Postman

Postman is an API platform for designing and building APIs. Postman's API Documentation Tool helps you generate, edit, and publish your docs. Since Postman has one of the largest developer communities out there, it makes sense to choose Postman's API Documentation Tool if you're already integrated within their ecosystem.

The screenshot displays generated documentation in the three-column format. Postman can automatically generate basic documentation based on your API's schema (i.e., an OAS file), but you can also add custom documentation in certain areas. For example, under Get a list of items, there's custom documentation to describe the operation in more detail. In the top right corner, Run in Postman also allows you to test out APIs directly from the documentation page.

Why Choose Postman?

Features: Postman generates documentation based on an API schema definition while also allowing you to customize and edit documentation before publishing.
Ease of use: Like most tools on this list, Postman can take an existing OAS file and generate documentation. It can also be used as a standalone app, or directly in the browser.
Community support: As a platform, Postman is perhaps the most popular for building APIs (more so than Swagger). This means it has one of the largest developer communities in the software development world.
Pricing: For up to three users, Postman's Free tier will do. For more integrations and capabilities, Postman's paid tiers are usually more cost-efficient than some of the other tools, with its Basic tier priced at just $12/user per month.
Limitations: Postman is a very powerful tool with many features, but this can make it overwhelming for users who are new to the tool or who only need to create simple API documentation.

Bump.sh

Bump.sh is a tool that's swiftly gaining popularity as it combines many of the best features from the previous five entries in this roundup.

To start off, you have OAS support: Bump.sh can take your existing OAS and instantly generate documentation for you.

Next, documentation is generated in a three-column layout, which offers an ideal viewing experience. In addition, Bump.sh supports AsyncAPI specifications as well, so it allows you to automate documentation for event-driven applications in addition to REST APIs.

Finally, Bump.sh's webhooks can be used to notify other tools and services each time you make a change to your API. For example, you could broadcast changes to a Slack channel or send email alerts to consumers. This helps you ensure that teams are notified when you make structural changes to your API.

Why Choose Bump.sh?

Features: Bump.sh can generate documentation not only from RESTful API specs like OAS but also from event-driven API specs like AsyncAPI. It also allows for custom documentation, automatically creates a changelog for you, and allows you to segment your API documentation into “hubs” for better organization.
Ease of use: You can set up Bump.sh in just a few minutes and quickly start generating documentation. Any OAS or AsyncAPI spec can be used as a starting point, making it a very easy tool to use.
Community support: Bump.sh is a new tool but has a growing developer community and customer base.
Pricing: Bump.sh is free to get started with. As you start to scale up, you'll need the Startup tier ($149/month) or Business tier ($599/per-month), although open-source projects can get access to all Business tier features for free upon request.
Limitations: Bump.sh doesn’t have an API Explorer yet, but you can use a Postman collection in the meantime. Like many tools like Postman or Readme, Bump.sh is not fully open-source.

Conclusion

API documentation is a task that developers should never overlook. Instead of manually updating documentation each time the API changes, many companies now use tools to automate doc generation.

In this article, you got a roundup of six of these tools, all with their unique features and capabilities. You could opt for a more minimal tool like Swagger UI or one that allows for more customization in both content and presentation, such as ReadMe. Of course, ease of use, community support, and pricing are important considerations to make too.

Bump.sh is the best way to automatically create API portals for internal and external users. It's also the only tool on our list that explicitly supports all OpenAPI specs (Swagger, v3.0, v3.1) or an asynchronous API definition like AsyncAPI, which is important for modern event-driven architecture (EDA). Feel free to look at our solution, and please reach out if you have any feedback, comments, or suggestions you'd like to share. We're always listening.

What are the different API types?

Jay Cormier — Thu, 08 Sep 2022 15:39:08 +0000

APIs have become increasingly popular over the past few years, enabling products, projects and people to connect. In this article, we will try to present a snapshot of the most popular solutions available as of August 2022. We did our best to avoid bias, but some technologies are not mentioned on purpose, as we want to focus on the most used/popular.

History

Always great to start from the beginning. If APIs have been here for a very long time, they began to get more and more popular in the early 2000s, when they got mainly used to push forward businesses on the web. Resellers or business partners could reach popular platforms, with APIs helping customers quickly find the products they were looking for on a single website.

Some of the biggest technology companies released their APIs like Salesforce or Amazon in a few years. Their impact on the industry is unmatched, as they forever changed how we sell and shop online.

We could continue this for a long time. After shopping, more APIs were released for different purposes and are now everywhere: social media, cloud computing, communication, mapping, voice AI…

RPC (Remote Procedure Call)

The simplest form of API interaction basically relies on executing some code on a distant server. RPC is probably the oldest type of API you could meet today. You can imagine it as a simple function with arguments but in a web context that makes them a web API.

RPC was designed for actions, executing procedures and commands with ease. One of the limitations is that it relies on the client mostly, which needs to know the endpoints and how and when to reach them. RPC itself is more an approach to APIs but with many existing specifications. We won’t talk about most of them but there’s one that is popular:

SOAP

Introduced by Microsoft and IBM around 1998, SOAP is an actual communication protocol. Known to use a bit wordy XML, SOAP is from the beginning a true API contract: its strict guidelines confer it an image of stability and safety. Today, SOAP is still found on some legacy systems which rely on it, but has mostly been supplanted by REST. Among the companies that use SOAP for their APIs, Salesforce is probably the most famous.

Learn more on SOAP.

More RPC types

RPC has known some evolutions since its creation. One of them led directly to SOAP: XML-RPC (basically, it continued to evolve until the decision to create a new standard from it). JSON-RPC has also been a bit popular at some point. Its main difference from XML-RPC is its capacity to handle notifications and work asynchronously.

REST

REST APIs quickly grew in popularity, pushing SOAP on their passage. While RPC is a strict protocol, REST can be seen as general guidelines which define a standard, normalized architecture for APIs.

Due to this, REST offers fast deployments in your environment. With URLs for the client/server relations, REST avoids the time-consuming part of writing code for each. Client and server can be developed on their side without information about each other, and their code can be updated without affecting the other.

Another important part of REST is its Statelessness: to make it simple, it means that clients and servers don’t need to know the state of the other one. REST uses standard HTTP operations and doesn’t need to code a specific interface. Messages sent are automatically understood, without knowing the previous messages sent.

REST supports webhooks enabling asynchronous requests. Imagine subscribing to an alert when a specific event occurs or when you need a reply/action from the server at a later moment.

There are many ways to describe your REST API but one of the most popular solutions lately has been to use the OpenAPI specification, previously known as Swagger.

Learn more on REST.

OpenAPI specification

While REST APIs were growing on the main stage, several actors worked hard to push this forward. One of the main issues was standardizing how APIs should be described. Swagger was one of these neutral description formats and eventually joined the Linux Foundation. The name changed as well to OpenAPI. Now the most popular standard to describe REST APIs, its community greatly supports OpenAPI specification.

Learn more on OpenAPI.

GraphQL

Initially created by Facebook in 2012, GraphQL was moved as an open-source project to the GraphQL Foundation in late 2018. GraphQL is a query language for APIs, focusing on delivering exactly the data requested and no more. Schema is essential to a GraphQL API, as it is your API’s single source of truth. A single endpoint can share the full capability in terms of data, allowing you to control the data you’ll receive from the server precisely. And when REST APIs could need loading from several endpoints, GraphQL handles this in a single request.

However, as many developers are more familiar with REST APIs, GraphQL may require a longer learning curve.

Learn more on GraphQL.

gRPC

Created by Google, gRPC is an open source RPC framework, cross-platform with many languages, relying on HTTP 2.0 as its transport protocol. Protocol Buffers (also known as Protobuf) can be used for requests/messages. Protobuf could be seen as Google homemade JSON (but faster, smaller and natively generating language bindings).

We won’t deep dive too much here, but gRPC has some significant advantages like its use of binary payloads (very light requests/code, better performances) or the use of HTTP 2.0 backstage.

gRPC may be considered as a strongly enhanced version of RPC.

Learn more on gRPC.

EDA

Unlike REST (which relies on a request/response workflow), Event-Driven Architecture API (or asynchronous APIs) works with a subscribe/publish system. Asynchronous APIs are based on a message workflow, allowing asynchronous actions. Instead of reaching out to a server to get a response, an EDA API will subscribe and receive specific notifications about an event, when required. In some cases, it could be considered a great solution due to its excellent performance and reliability, like for a heavily requested server.

Asynchronous APIs are very popular in microservices environments, helping them to synchronize data across different services.

They have been growing in popularity over the years, receiving more and more support from the developer community. If asynchronous APIs can work with many protocols, a standard emerged to bind them all within the specification:

Specifications

AsyncAPI is an open source standard describing an EDA API’s specifications, working with many possible protocols. Based on OpenAPI, AsyncAPI has optimized these parts for asynchronous needs: Designed from the idea of a messaging system where the messages are built with a header and a payload, helping to sort them into topics.

AsyncAPI focuses on the application and the communication channels and works well with CloudEvents, another standard for asynchronous APIs that focuses more on the event itself and the message format.

Learn more on AsyncAPI.

Most commonly used protocols

We’re covering below a few protocols that are popularly used within an EDA API, but there are many more!

AMQP

Initially created by JPMorgan Chase in 2003 to build an open communication standard, AMQP has been supported by some of the biggest: Microsoft, VMWare, Cisco Systems and several banks like Barclays.

Among others, AMQP’s biggest advantages are its support of annotated data and its self-describing encoding system, which permits greater compatibility with clients.

Learn more on AMQP.

MQTT

MQTT is a bit older than AMQP (1999) and was initially created to watch over an oléoduc in the desert. As the satellite connection was expensive, the goal was to have a bandwidth-efficient, battery-power-efficient protocol.

MQTT never stopped to evolve and is now one of the most popular protocols in the IoT field, thanks to its support of unreliable networks.

Learn more on MQTT.

Kafka

Kafka is often considered an alternative to “traditional” message brokers. Designed by LinkedIn, Kafka was meant to support the high volume of messages transiting through the platform. It quickly then switched to open-source in 2011, under the Apache Software Foundation.

Uber uses Kafka to help match passengers and drivers. More than 300 microservices rely on Kafka now and the protocol is considered the backbone of their architecture.

Learn more on Kafka.

WebSockets

WebSocket protocol has been here for a long time, standardized in 2011, and is supported natively by most browsers. Offering a very flexible implementation, you can easily find many resources online and a solid tooling experience.

WebSockets APIs are stateful (meaning that the connection between client and server remains active until stopped by one of them) and full-duplex (can send/receive simultaneously).

Widely spread in the EDA ecosystems, WebSockets are increasingly partnering with REST APIs to add an asynchronous layer to them.

Learn more on WebSockets.

Conclusion

This article was just a short tour of today’s API scene, as there’s much more to share on this growing, vivid topic. New concepts, ideas, projects, tools, standards, and optimizations are developed and shared weekly within the community. And even if we know that some content in this article will be obsolete in the upcoming months, we’ll try to keep it updated as much as possible.

In the meantime, we at Bump are trying to create great tools to help developers, API evangelists, communities and teams to get the best from their APIs. We have developed the first product that provides a unified experience around OpenAPI and AsyncAPI. Feel free to look at our solution, and please reach us if you have any feedback, comment or suggestion you would like to share. We’re always listening. :)

What is AsyncAPI?

Jay Cormier — Wed, 16 Feb 2022 17:11:47 +0000

AsyncAPI is the most popular specification for describing asynchronous APIs and Event-Driven Architectures.
Open-source and partially based on OpenAPI standards, AsyncAPI has been a solid and efficient answer to asynchronous communication needs, especially since its 2.0 version.

A brief look at APIs’ history

Let’s start by explaining, very simply, APIs.

A long time ago, communication between applications or services required you to deep dive into their code if you had access to it, which could take quite a while if they were many (or messy). APIs have been created to make this part of programming much easier: APIs tell you precisely what you can ask to an application and what to expect in return, without seeing what the application does underneath.

At first, almost every API had its own way of working and communicating. And if documentation was missing or outdated, it would quickly become a mess. Different standards were built, but one of them ultimately rose to the top: OpenAPI.

OpenAPI (previously called Swagger until version 3.0) has been the most popular choice for REST APIs, solving documentation problems and creating a good standard. Now part of the Linux Foundation, we covered OpenAPI recently in another blog post. We even have a fantastic example right here.

What about asynchronous APIs?

Choosing between a synchronous or an ansynchronous API is basically an architectural decision. If classic synchronous APIs are helpful when you expect a response to any request you make, asynchronous APIs can be useful in other situations like telling application that some event occurred without expecting a callback or storing data on a device with connection issues.

For example, we could think of a chef working in a restaurant. An asynchronous API (here, the waiter) would suit this perfectly as the kitchen just need to get the dishes and the table they belong to. You can even imagine richer messages, including food allergies or meat cooking requests. You do not expect a reply from the kitchen every time.

Here comes AsyncAPI: built with OpenAPI’s legacy in mind and sharing some concepts with, it uses some parts of its original structure and optimizes them for asynchronous needs.

Definitions

AsyncAPI specification

Consider this as the guidelines to describe your asynchronous API to ensure that you follow the standards.

AsyncAPI definition

aka AsyncAPI file / document / description

This is the part you produce, explaining exactly how your API works, what it can or cannot do, what data it accepts and returns.

AsyncAPI documentation

The human-readable documentation of your AsyncAPI definition. It can be automatically generated to save time.

What does it look like?

AsyncAPI documents can be written in YAML and JSON. This example will use YAML, as it’s the most popular and readable format. Let’s have a quick look:

asyncapi: 2.3.0
info:
  title: Hello world application
  version: '0.1.0'
servers:
  production:
    url: server.cogip.com
    protocol: amqp
    description: Absolutely official COGIP server.
channels:
  hello:
    publish:
      message:
        bindings:
          amqp:
            contentEncoding: gzip
            bindingVersion: 0.2.0
        payload:
          type: string
          pattern: '^hello .+$'

AsyncAPI document structure

Right after the document type and its version comes the info object, which contains at least the title (the name of your API) and the version (don’t forget to change it after every update).
servers tells where and how to connect to your message broker or server. You need to specify a protocol, like amqp, mqtt or ws for instance, and a url.
With AsyncAPI, you use channels (like the paths in OpenAPI) to send your message to the application. This section details how messages flow through.
The payload is the part where you explain how message are made: types, format, pattern, etc...
bindings describe protocol-specific information. It can be defined specifically at the message level or generally at the servers level.

AsyncAPI benefits

If OpenAPI is HTTP and endpoints oriented, AsyncAPI allows many protocols, as we have seen before in the server section of the document, but also more API styles (request/response, publish/subscribe, etc...). AQMP, IBM, Kafka, MQ, MQTT, SNS, WebSockets, JMS for the most popular.

Tooling

AsyncAPI has gained more and more popularity since its version 2.0. Great tools are continuously developed by the AsyncAPI community, and here’s a short selection from our favorites:

Editors

AsyncAPI Studio: Still in beta, this tool was expected from the community. Great to start playing with the standard.

Validators

Mocking & Testing

Documentation

Bump.sh 💙
AsyncAPI Generator

AsyncAPI has a fantastic list of valuable tools that make the difference for most use cases, you may want to check it out.

More resources

We hope this short tour of AsyncAPI made you want to try it yourself. We strongly suggest giving it a try with the AsyncAPI Studio, or even find some public examples like these ones:

Bump was one of the first SaaS products to believe in and support AsyncAPI since its 2.0 release. We have worked continuously for the past years, convinced that it will become the same strong standard to asynchronous APIs that OpenAPI is to the REST world today.
We are proud to be one of AsyncAPI’s Bronze Sponsors and we hope you’ll enjoy coding with AsyncAPIs as much as we do.

If you have any questions or comments, feel free to reach out. We’re just a mail away from you!