Do We Describe Streamdata.io Proxied APIs Using OpenAPI Or AsyncAPI, Or Both?

I am using OpenAPI definitions to turn existing JSON APIs into streaming APIs using Streamdata.io. For example, I can take the OpenAPI for the Alpha Vantage financial data API, and automate the proxying, and streaming of market data pretty quickly. I can repeat this for any of the APIs we are profiling for the Streamdata.io API Gallery. As we are doing this work, we have begun asking ourselves, how do we now provide a machine readable index of the resulting streaming API we have just created? Can we describe this new proxied API using OpenAPI format, or should be looking to use the emerging AsyncAPI format? Or both?

The current Streamdata.io service doesn’t push the resulting streaming API out of the realm of being an HTTP request, it just becomes a long running HTTP request, with a shift in how the payload is defined. I’m just unsure how we can describe the long running nature of the resulting API in OpenAPI, as well as define the schema for the slightly different payload, which has an id: and data: wrapper for each response. For the moment, I’m thinking that defining the resulting API produced using the OpenAPI specification is the most sensible path forward. I may have to introduce a handful of vendor extensions to accommodate the streaming nature of the HTTP request, but I’m feeling like AsyncAPI might be overkill for providing a machine readable definition of an HTTP API that is only employing Server-Sent Events (SSE).

However, knowing the road map for Streamdata.io, and looking towards the future where I have hundreds of APIs cataloged as part of the Streamdata.io API Gallery, tagged by the topics and events they deliver, then proxied and delivered as streaming APIs, I’m thinking that an additional AsyncAPI definition might be in order. I’m feeling like I will be able to use both API definition formats for describing what Streamdata.io delivers. I can describe the HTTP web API we are proxying, as well as the resulting streaming API using OpenAPI. However, this process will add an event-driven, message defined layer to existing HTTP APIs, where using AsyncAPI to define the API surface area, as well as catalog the topics being served up will make a lot of sense.

AsyncAPI is in its early stages. That is alright, so am I with the development of the Streamdata.io API Gallery. I’m learning a lot as I profile and catalog different types of APIs. I’m evolving in how I define the OpenAPI definition for the APIs I’m cataloging, and getting more precise in how I tag them. Right now I’m happy to create two separate OpenAPI definitions. One for the original API, and a separate one for the resulting streaming API–I will be indexing them both in the APIs.json for each project. Once I better understand the surface area of each API, and the topics present within each one, I’m confident a vision for how I can use AsyncAPI will come into focus. Resulting in a pretty interesting event-driven layer that can augment existing HTTP APIs, moving them into the future, and allowing for consumers to publish and subscribe to the meaningful events we’ve catalogued using AsyncAPI.

Lots to think about. Lots of work to be done. Once I get 10 separate areas of the API Gallery profiled, I will be spending more time playing with what is possible with AsyncAPI, and their proposal for defining topics. Then I’ll think I will have more to share regarding my usage of OpenAPI and AsyncAPI for describing what Streamdata.io delivers.