Continue Pushing The API Documentation Conversation Forward

I am been finally seeing the investment across the API sector I wanted to see when it comes to API documentation. There are multiple API definition driven API documentation offerings available on the market now. Both open source and high quality commercial services. A couple years after Swagger UI made it’s splash I began lobbing for more investment in open source API documentation tooling, and after four years I’m starting to see it beginning to happen. However, let’s not rest on laurels and make sure we keep investing and building on the momentum that we have established, and continue making API documentation more valuable to developers, but also to business users who are interested in putting API resources to work.

One of the major improvements in API documentation that I would like to see in coming years centers around visualizations. I’d like to see interactive documentation be augmented and extended using D3.js, and other visualization components, rendering API responses in a more visually pleasing way. Helping make API responses more meaningful to developers, and potentially to businesses users who are trying to understand the value an API delivers. Visualizations have the potential to make API documentation something that introduces and educates developers to how to integrate with an API, but also demonstrate and illustrate how the data, content, and other resources can be valuable. Bonus points for any tooling provider if the visual results are actually embeddable and shareable across websites and social media, allowing anyone to take the results of each API response and quickly make available to a developer or business users network.

Beyond just visualizations, I’d like to see more interactive API documentation to make results savable, exportable, and shareable. Allowing any developer or business user to easily make an API request, then export the results as a JSON, CSV, or possibly as a spreadsheet. Empowering API consumers to quickly use API documentation to understand what an API delivers, get at the valuable at the data, content, and other valuable resources, and take that value with them in a portable machine readable format. This type of functionality would move API documentation to be more executable like we see Postman doing with their API lifecycle tooling, documentation, and resulting Postman Collections. Ensuring API documentation is not just interactive, which is a default requirement these days, but it is executable functionality that can be shared and taken with you, allowing anyone to run the desired API request at any point in the future.

These are just a handful of ways I’d like to see the API documentation conversation continue to be moved forward. I have a lot of other ideas regarding how API documentation can be made more useful, and empowering for both developers and business users. Interactive API documentation like Swagger UI, Redoc, and others have gone a long way in helping make APIs more accessible and usable amongst developers. With another push, I think we can also make APIs more accessible and useful to business users, and dramatically increase the reach of APIs beyond just the tech community.  Which will be necessary to realize the next wave of growth and adoption we are looking for when it comes to APIs, and ensuring they continue to be ubiquitous behind the desktop, web, mobile, device, and network based applications we depend on each day to get business done—ensuring APIs aren’t just a behind the scenes developer tool, and can be used by virtually anyone.