Developers love to reverse engineer functional aspects of API operations, and they see code and artifacts as just puzzles. The best way to get technically minded folks engaged with your stories is to make them hands-on in some way. Actually, it is an increasingly valuable way to get business stakeholders involved by telling stories and providing hands-on artifacts for sales, support, and other functions. These are a handful of ways in which you can extend a simple blog post or a video and make it something that anyone can take back to their workspace.
- APIs.json - The machine-readable business details.
- OpenAPI- The machine-readable technical details.
- JSON Schema - Standardizing JSON or YAML schema.
- Collection - Portable, documented, executable collections.
- Environments - Workable and reusable environments.
- Jupyter Notebook - A downloadable walkthrough for API.
An APIs.json could be used to generate a README, the OpenAPI can be used to produce a mock server, and a JSON Schema can help validate JSON data being passed around. Increasingly Postman and Bruno collections, as well as Jupyter Notebooks are also being given to support, sales, and product managers to engage with different aspects of API operations. It doesn’t take much to make a story more hands-on, and the OpenAPI you are already using for documentation and code generation is a good place to begin, making your storytelling a littler sticker with consumers.
