We’ve been profiling hundreds of APIs using the OpenAPI specification format. OpenAPI, formerly known as Swagger, allows us to describe the surface area of HTTP (web) APIs using JSON or YAML, providing a machine readable definition of what is possible with an API. While all of the APIs we are profiling are purely request and response based APIs, as we profile using OpenAPI, we see a wealth of untapped streams, and event-driven signals that aren’t being subscribed to. We are just beginning to make sense of this opportunity, and wanted to share what we are finding with you. So let’s talk about how OpenAPI tags relate to topic streams.
Using the Stocktwits Stream Symbol API as an example (which isn’t actually a streaming API), we wanted to demonstrate, how a normal web API, can be profiled using OpenAPI, and help establish a map for the event-driven nature of the API. Which can then be turned into real time topical streams, using Streamdata.io. Here is a snippet from the OpenAPI for the StockTwits Stream Symbol API to get the conversation going.
The definition provides a machine readable definition for a single Stocktwit’s API path, which also provides the details of the stock ticker symbol parameter you will need to pass in as part of the path. I’ve included a handful of ticker symbols as enum values to demonstrate how this work, but in reality you will have ALL the ticker symbols to work with, not just four of them. Using this example, we have four potential topical streams we could create and subscribe to for a single request / response API:
Apple Market Social Data
curl -v "https://streamdata.motwin.net/https://api.stocktwits.com/api/2/streams/symbol/aapl.json &X-Sd-Token=[streamdata api key]""Twitter Market Social Data
curl -v "https://streamdata.motwin.net/https://api.stocktwits.com/api/2/streams/symbol/twtr.json &X-Sd-Token=[streamdata api key]""Facebook Market Social Data
curl -v "https://streamdata.motwin.net/https://api.stocktwits.com/api/2/streams/symbol/fb.json &X-Sd-Token=[streamdata api key]""Microsoft Market Social Data
curl -v "https://streamdata.motwin.net/https://api.stocktwits.com/api/2/streams/symbol/msft.json &X-Sd-Token=[streamdata api key]""To programmatically generate these streams, all you have to do is take the machine readable OpenAPI, assemble the base url and path, and iterate through each enum value present for the path parameter–in this case it is the stock ticker symbols. The results are four separate streams of data, receiving updates in real time using JSON Patch, on top of an exist web API that relies on a traditional request and response model. This is just a single example of the event-driven, streaming opportunities that exist out there when you begin profiling APIs using OpenAPI, and making sure you provide complete definitions of the parameters, enums, and tags for each path–these values are what become the topical descriptions in an event-driven world. OpenAPI tags open the door to topic streams.
We purposefully used the Stocktwits API as an example of this potential. 1) They need a real streaming version of their API using Server-Sent Events (SSE) (pssst, call us!), and 2) they aggregate their data from a variety of existing social sources, namely Twitter. Demonstrating that you can do interesting things on top of existing APIs, but streaming also adds another dimension to the conversation. We have several hundred OpenAPI definitions indexed as part of our Streamdata.io API Gallery work, and we are adding more of them each day. Along the way we are beginning to define the streaming topic opportunities that exist on top of the existing API landscape, with this being the first of many posts looking to wake you up to the possibilities for crafting meaningful streams that others can subscribe to using Streamdata.io.
Follow us on social