Describing The Websocket API Using An AsyncAPI Definition

We are pushing forward our work to define the world of APIs using the OpenAPI definition, so that we can include APIs in the API Gallery. To be included each API must have a machine-readable API definition, then it can be indexed as part of the gallery. This API profiling is delivering a wealth of APIs that can be used in a variety of applications. We’ll keep adding APIs to the gallery, but we also wanted to get to work profiling streaming APIs using a new format called AsyncAPI, which provides a machine-readable way to describe event-driven messaging APIs, in the same way, that OpenAPI does for more request and response based APIs.

The AsyncAPI is just getting started, and we are still learning what it is all about, so please look at our work as more of a draft specification, than something that should be considered a format definition. To learn more about how to apply the AsyncAPI, we wanted to take some of the existing streaming APIs we’ve come across in our work, and take some time to define using the format. We took one of the 16 Blockchain WebSocket API we profiled last week, and used it to push forward our knowledge of the APIs, as well as how to apply the AsyncAPI specification. To get started we took the WebSocket API, and crafted this draft AsyncAPI specification.

Describing The WebSocket API Using An AsyncAPI DefinitionThis is our first crack an using AsyncAPI, so we aren’t 100% sure if everything is the way it should be. We added three main subscription topics, as well as the basic ping subscription. We included the message schemas for transactions and block. One thing we are a little fuzzy on is how the topic subscriptions definitions translate into specific requests made to the API. While the topic structure proposed by AsyncAPI makes sense, we don’t quite see how it translates into the way WebSocket API receives subscription requests. We’ll keep playing around with it until things come into focus, but we wanted to share our learning process with you here on the blog.

We will be profiling all 16 of the Blockchain WebSocket API we have profiled. We are also going to work to produce Async definitions for some of the web APIs we proxy using and turn them into more event-driven streams. We’d like for the API Gallery to provide access to regular request and response centered web APIs, event streams are already out there that use WebSocket, as well as the streams we are enabling with Server-Sent Events (SSE) technology. We envision the API gallery reflecting the API landscape by providing access to APIs that you can request individual responses from, as well as a wealth of real-time topical based streams that you can subscribe and unsubscribe to as you desire.

A Modern API Toolbox

**Original source: blog