Some API Specification Toolbox Projects That Will Make an Impact

I have been conducting weekly discussions around API specifications each Friday mornings which I call the API Specification Toolbox. The goal is to just identify ways in which we can drive more discussion and participation in API specifications, focusing on OpenAPI, AsyncAPI, JSON Schema, GraphQL, and Postman Collections. My goal is to help increase awareness of these specifications, but more importantly get more people sharing what they are working on and invest more time and resources into supporting the specifications. I conduct an hour of informal discussions from 8:00 AM to 9:00 AM PST each Friday, and we record as many of our ideas and talking points on Github using issues. Some interesting ideas have emerged from the discussion, and I am taking some of the lowest hanging fruit from these ideas, organizing them, and working with the OAI, AsyncAPI, JSON Schema, and Postman team to try and bring some of these ideas to life. There are many other ideas that didn’t make my starter list of project, but these are the ones I feel are the most important, would have the the greatest impact, and be achievable in small bursts of work, and to help drive some conversation I am having, I wanted to flesh out some of the top ideas here on the blog.

I cleaned up the titles for each of these ideas, and grouped them based upon the type of project, and I would like to flesh out a little more, identify how they overlap and are related—then work to actually push them forward without me doing all of the work. I feel like with some assistance from the wider API community, and some investment from the OAI, AsyncAPI, JSON Schema, and Postman, these projects could make a pretty significant impact on what is going on across the API landscapes. My objective with this post is to show how all of these projects can feed each other, and see what I can convince the community, and each specification to help move forward. Providing me with the words I am going to need to sell these ideas to anyone who will listen, and potentially help make things actually happen.

Mapping The Landscape

I feel this area is one of the cornerstone deficiencies that slows the forward motion of the specifications, services, and tooling. In my opinion, everything is dependent on these four areas, meaning if we can clearly articulate the services, tooling, and people involved with these API specifications, and understand how they are extending the specification, all of these specifications and resulting tooling will lurch forward without any clear vision or coherency. As a community, we need to be able to efficiently profile and publish directories of services, tooling, people, and extensions, and do it in a way that can paint a full picture of what is going on. These are the four core projects I feel are needed to map the API specification landscape.

Service Providers #19 - Identifying, profiling, and publishing a directory of API service providers who have adopted API specifications.
Open Source Tools #7 - Identifying, profiling, and publishing a directory of open source API tooling who developed on top of API specifications.
People #20 - Identifying, profiling, and publishing a directory of people who are working on the specifications, and doing things with them.
Specification Extension #24 - Identifying, profiling, and publishing a directory of specification extensions that are in use across the space.

I pulled together a simple Jekyll single page application that runs 100% on Github for service providers and for tooling, and can apply the same “toolbox” approach to people and extensions. It provides an open format that anyone can fork and replicate, publishing their own full or sub-directory. Next, I wanted to identify a handful of things that will be needed to move these forward to help drive some conversations about more investment in making these directories happen—here is what I am thinking about right now.

Single Page Application - I already have a blueprint for these single page catalogs that are driven using the APIs.json specification, and use Jekyll and Github Pages to allow them to run 100% for free on Github. I have written up the approach, and will be working to apply to these projects as work gets done.
Intake Questionnaire - We need an intake questionnaire for each of these directories that can be used when approaching service providers, and tooling creators, as well as a checklist when profiling people and vendor extensions, making the process that anyone can do to help move things forward.
Discovery - While I have pulled together a seed list for service providers and tooling, there will be a lot more work ahead to find new ones, as well as work to find interesting people and what the different extensions are for each of the specifications, bringing new entries to each of these API specification catalogs.
Outreach - We will need one or many people to actually reach out to service providers and tooling creators, and encourage them to fill out the intake questionnaire, then add the information to the APIs.json data stores behind each of the directories, building out the catalogs and ensuring information is correct.
Research - It will take a significant amount of research to find people who are doing interesting things with API specifications, and discover the extensions that exist out there, with an emphasis and focus on OpenAPI extensions to begin with, demonstrating how folks are extending the specification.
Evangelization - It will take some serious evangelism to help get the word out about these directories as they are being built, pushing the service providers, tooling, and people to help spread the word as they are being engaged, as well as invest in ongoing storytelling and amplification about the directories in an ongoing way.

I am using GitHub to move each of these projects forward. There should be an issue added for each service provider, tool, person, and extension. This provides a feedback loop to be established that people who are working on the catalogs can use to record activity and engage with the community. Each issue can be used to handle intake for each entry, evolve each of them, and provide an ongoing feedback loop for each entry, as well as each catalog. It is going to be tough to put a scope and price tag on all of this work, but it seems like there should be a set amount of hours each month that can be dedicated to this work, and recruiting volunteers as well as a handful of paid workers. As I will demonstrate, this work will lay the foundation for other projects I am advocating for, as well as help strengthen and grow the entire API economy.

Self-Service Virtual Storytelling

The next group of projects I would like to see invested in after mapping out the landscape, involves telling the stories and incentivizing conversations about why API specifications matter, and what people are doing with them. All three of these ideas overlap with each other when it comes to content, topics, and potentially coordination. Making them pretty ripe for doing all together, helping provide a rich set of ongoing conversations about the specifications and what they enable.

Video Interviews #3 - Conducting a regular stream of video interviews with people who are developing the specifications, as well as what people are doing with them across APII service and tooling providers, as well as API providers themselves, and possibly the developers who are integrating with the APIs that use them.
Podcast #25 - This could be a pure audio version of the same video interviews above. Maybe we only do one of the formats, but ideally they are done as video interviews, and the audio gets mixed and published as a podcast, covering a wider spectrum of viewers and listeners who may want to engage in different ways.
Forums & Workshops #8 - Moving beyond just interviews and conversations around the specs and service and tooling space, regular forums could be held that teach people about specifications, tooling, and common practices provided regularly scheduled forums and workshops that help educate the growing API specification community.

These interviews, conversations, and forums could be cultivated from the work above on mapping the API landscape. Bringing in service providers, tooling creators, and people doing interesting things across the space, and getting them involved in doing the interviews, participating in the conversations, and leading the forums and workshops. Here are some of the elements that will be needed to help move some of these things forward as part of these projects.

Participant Discovery - Finding the people who will be engaged in these interviews, conversations, forums, and workshops.
Participant Handling - There will be work to handle the scheduling and coordination needed to keep a steady stream of people.
Topic Discovery - More work is needed to make sure relevant topics are discovered and brought to the table for this storytelling.
Video and Audio Production - There will be regular work to edit and produce each of the videos and podcasts being published.
Publishing and Syndication - Once a video or podcast is ready it will take work to publish and syndicate across relevant channels.
Single Page Application - It would be nice to also publish a single landing page that catalogs all of this content as part of the effort.

I am sure there is a lot more work to be done here, but I am just looking to get the main talking points down right now. Then I will open up for discussion during the API Specification Toolbox office hours, and as part of the conversation I am having with the OAI, AsyncAPI, JSON Schema, and at Postman. I really see this self-service virtual storytelling and the mapping of the API landscape all working together in a virtuous cycle that expands the awareness and literacy around API specifications.

Information and Propaganda

The last grouping of ideas I’d like to see happen. I am dubbing information and propaganda because it is all about further expanding the narrative and visual storytelling that exists around the specification. Rounding of the virtual storytelling above with a regular heartbeat from a newsletter, as well as more static longer form content and visual storytelling that helps reinforce what API specifications deliver, and the impact they are making across the software development lifecycle. Here are the three projects I’d love to see get some investment from the community as well as the API specifications themselves.

Community Newsletter #12 - Putting out a regular newsletter that showcases the specifications, services, tooling, people, and interesting conversations going on across the sector.
10 White Papers #5 - Produce a series of white papers that showcase the impact API specifications make on the API lifecycle on the ground within enterprise organizations, providing an overview of what people need to know.
Propaganda Posters #9 - Add a visual layer to the API specification conversation, developing a series of old school propaganda posters that get people motivated about API specifications, and collecting the different posters defining this time of technology.

I have already started pulling together a handful of pilot newsletters, fleshing out the format and topics—I just haven’t sent them or built the lists. I haven’t done any work on the white papers or propaganda posters, but would like to actually start detailing what they may be about. I think these are great projects to bring together the community and the specifications, while providing a regular drumbeat about the space, and reliable content that newcomers can use to get up to speed, and keepsakes that the most passionate can collect to capture a piece of this moment. To help move these projects forward, here are some of the areas I would need to work on fleshing out a bit more.

Newsletter Format - I have already pulled together a proposed format outline for the newsletter, and pulled together issue one and two, trying to seed this project.
Weekly Newsletter - Providing dedicated resources that would actually pull together the newsletter each week based upon submissions, and get out the door.
White Paper Topics - Pick 10 (more or less) topics for each of the API specification white papers, providing what people are needing to learn about the most.
Find White Paper Authors - Identify the authors who are best suited for actually creating each of the API specification white papers.
Produce White Paper Content - Actually write each of the white papers and then edit them, getting them ready for production.
Publish White Papers - Formerly produce each of the white papers, putting a polish on them and getting ready for public consumption.
Syndication - Invest in actually publishing and syndicating each of the white papers, helping make them available outside the specifications.
Poster Topics - Identify the topics for each of the propaganda posters, picking the most impactful areas in which API specifications are making a difference.
Poster Artist - Find an artist who can actually produce each of the propaganda posters, and provide use with the finished product that will work.
Poster Syndication - Establish a strategy for making the posters available and get them out to the community in a way that will make them memorable and exposed.

These are just talking points I can use to help drive some of the conversations I am having. There will be a lot of things to do that I am not seeing, but I wanted to make a first pass at what the scope of these projects might be. Clearly the newsletter will take an ongoing effort, but the white papers and propaganda will take a heavy one time lift, with light touches after that. While we may not be tackling all of these, I wanted to lay them out in hopes that we can at least tackle one or two of them.

Stabilizing and Amplifying the API Specification Toolbox

The service provider, tooling, people, and extensions directories would help us define the API landscape. This would have a stabilizing effect on the conversation. Helping people understand what exists, but more importantly help us stabilize what will and should come next. Then the virtual events, information, and propaganda will help amplify this increasingly well defined API specification driven landscape. It is crazy that there isn’t an authoritative source of services and tooling, and I am always amazed at how interested folks are into talking and sharing knowledge about the API specifications, with so few outlets for all of this to occur. I am regularly amazed at what I come across going on with OpenAPI, AsyncAPI, JSON Schema, and Postman collections as I do my work as the Chief Evangelist for Postman, and API Evangelist each day. I come across compelling stories coming out of top tier API providers about how they are using all of these specifications, with an appetite for telling these stories, and there are very few specification centric outlets to point them to. There is the API specification conference, which was born out of my event API Strategy & Practice, but beyond this there isn’t anything else dedicated to the growing API specification dimension of the API economy.

OpenAPI, AsyncAPI, JSON Schema, and Postman Collections are defining almost every industry in 2020, mapping out the data, content, algorithms that are powering business today. These API specifications are defining the resources behind the desktop, web, mobile, device, and network applications powering our personal and professional worlds. API specifications have grown significantly over the last ten years, and we are going to have to ramp up our investment in these specs if we are going to take things to the next level and realize the potential of what we have all been calling the “API Economy”. I feel like this list of ideas represents how we can light the fire under all of this and begin stabilizing the conversation and driving it all forward. I just have to figure out how to make it all happen without me carrying the entire load. I am already moving some of these projects forward in one way or another, but to be able to do it at the scale we need I am going to need more people and investment from the specifications, services, and tooling providers. Alright, now back to the dog and pony show around this production, selling it to the people I need to help me move this stuff forward—more to come as I further refine each of these ideas and come up with actual plans for executing on them.