We are working closely with Axway on a number of projects over here at Streamdata.io. After we got out of a meeting with their team the other day we received an email from them asking if we had an OpenAPI definition for a demo Streamdata.io market data API. They were wanting to include it in some marketing materials, and needed a screenshot of it. To be able to generate the visual they desired, they needed an OpenAPI to make it tangible enough for capturing in a screenshot and presenting as part of a larger story.
This may sound like a pretty banal thing, but when you step back and realize the importance of OPenAPI when it comes to communication, and making something very abstract a tangible, visual thing, it becomes more significant. You can tell someone there is a market data API, but taking a screenshot of documentation generated via an OpenAPI which displays the market data paths, a couple of parameters like stocker ticker symbol and maybe date range, and then plug in some actual values like the ticker symbol for AAPL, and show the JSON response takes things to a new level. This is OpenAPI empowered storytelling, marketing and communications in my book. Elevating what OpenAPI brings to the table to new stops along the API life cycle.
This isn’t just about documentation. This is about making an abstract API concept more visual, more meaningful, and able to be captured in an image. Axway is trying to demonstrate the value of their API solutions, coupled potentially with Streamdata.io services, in a single image–providing a lot more rich context, and visualizations that amplify their marketing materials. This isn’t just documenting what is going on so that developers know what to do with an API, this is telling stories so that business users understanding what is possible with an API–using a machine readable format like OpenAPI to help deliver the 1000 words the image will be worth.
Using OpenAPI like this reflects where I’d like to see API documentation go. Sure, we still need dynamic API documentation driven by OpenAPI definitions for developers to understand what is going on, but we need more snippets, visualization, and emotion driving solutions to exist. Things that marketers, bloggers, and other storytellers can use in their materials. We need OpenAPI-driven tools that help them plug in a relevant API definition, and generate a meaningful visual that they can use in a slide deck, blog post, or other material. We need our API documentation to speak beyond the developer community and become something that anyone can put to work in their API storytelling efforts–no coding required.
