For some workshops preparation this week, I needed to isolate just the best of the API calls and documentation from handful of APIs I am trying to teach my intended audience about. I have almost twenty separate companies targeted, with a couple hundred individual endpoints across the API provided served up by these companies. I needed to a way to easily define, organize, and present a subset of API samples, intended for a specific purpose audience.
In this workshop, I need the simplest, most intuitive samples possible across these popular APIs. For Twitter I need to be able to just send a tweet, or list friends, and on Facebook I need to post to my wall, and search for user. I need simple actions, that will be meaningful to my higher education audience--most likely students. I don't want to bury all of them with the endless API possibilities that surround the APIs I'm showcasing, I need the twenty use cases that they'll give a shit about, and result in them being interested in what an API is.
As I do with all my research, I organize my lists of APIs into APIs.json collections, and publish the results as a Github repository. This allows me to quickly assemble, relevant collections of APIs, designed for specific audiences, in a way that I can wrap with informative content and stories, helping them on-board with the importance of APIs, as well as the individual APIs. This got me thinking, because as part of an APIs.json index I have all the moving parts identified, I just need a way to simplify, and distill down into little API samples, so that I can offer up through the experience I am crafting.
To help me in my effort I started defining a new APIs.json API type schema, which allows me to define a sample subset of any API I have defined using OpenAPI Spec. Within each schema, I can map to a specific endpoint + method present in the OpenAPI Spec, select which parameters will be used, and what the default values and enum will be applied. I also provide a title, description, and now I have a machine readable schema for my API sample. Next, I just need to craft a simple API Samples JS library for rendering these samples into widgets and other embeddable goodies.
Each sample will use the security definition defined within the OpenAPI Spec to get the authentication details it needs, render it as a simple widget, which allows users to quickly make a relevant API request, and see the results immediately. This really is no different than API explorers and interactive docs like Swagger UI, but rather than providing a complete UI or docs, it provides just a sample, to help educate the API consumer around what is an API, as well as what any single API does.
While I think samples can live alongside the regular API docs, and explorers, within the portal of each API, I'm thinking they will become exponentially more valuable when used in a hacker storytelling, API broker, and evangelism setting. I have the base JSON schema defined for my API Samples, and once I get a working prototype for the JS client, I will publish a simple page, demonstrating a few use cases. At first I'll just be using to help people understand the value of APIs in general, as well as specific APIs, but I think future I will be able to get more sophisticated in how I tell stories around stacks of APIs, and how APIs can be assembled to accomplish bigger things than just any single API can accomplish on its own.
Hopefully in the near future, I will have a wealth of API Samples for the most important APIs I profile as part of my API Stack work, providing me with some valuable education and storytelling tooling to assist me in my evangelism work.
