Someone Please Build My Open, Interactive, Portable, And Visual API Documentation Toolkit24 Oct 2014
I wrote about visual API documentation a few months back, after I looked at the approach from OpenFDA, and now after taking a look at the value Slate brings to API providers like Dwolla, these feelings are re-surfacing in my mind. Since I have limited time, I’m getting pretty good at putting my ideas out there, allowing anyone to step up and execute on opportunities I’m seeing across the API space—I just do not need the extra work.
I love me some Swagger UI, as you can tell from the fact that all of my APIs use Swagger as the API definition format, as well Swagger UI for the interactive documentation. I’m pretty convinced of the importance of documentation being a hands-on experience, but after looking at approaches like OpenFDA, and Dwolla with their Slate driven API docs, I’m convinced they should also be more beautiful and functional.
Let me explain what I would like to see developed for the API space:
- API Definition Core - As we are beginning to see across the space with current interactive API documentation practices, everything needs to be driven by a machine readable API definition, providing a set of instructions for how any user will engage with an API.
- Interactive - In 2014 the bar is already set, and API documentation should be interactive, allowing users to make live calls to a demo, or production API, making learning about an API hands-on experience.
- Inline Code - The tools are available to generate code samples from Swagger and API Blueprint, and wherever we make an API call, we should also be able see the code for making the call inline, side-by-side with wherever I am engaging with the API—in my language of choice please!
- Visualizations - I don’t want just to get back a response from the API, I want to be able to visualize the value returned from an API. I would like a suite of D3.js visualizations for each API endpoint I’m interacting with, allowing me to immediately see the value generated by each API.
- Spreadsheet - Allow me to export a CSV, or more robust Excel or Google Spreadsheet representation of an API. Sure, this would not be applicable to all APIs, but would bring a lot of value to many APIs out there. APIs aren’t just for developers in 2014. Oh, and make me the D3.js code for any visualization too copy & paste as well.
- Embeddable - I enjoy being able to deploy my Swagger UI to any Github repository using Github Pages, and I think portability is essential for the success of API engagement. I want to be able to copy & paste API expressions, visualizations, and other simple, easy to use widgets to any site, anywhere—no coding experience necessary.
- Open Source - If you are building something like what I’m describing, it really should be open source so that all aspects of it can be reused, by anyone, anywhere. It just doesn’t make sense to be a proprietary, closed solution, and you if are building something in this way you owe me $1 million dollars for my ideas. ;-)
API docs have become much more than just API documentation, they have become about API discovery, education, expression, collaborations, and interactions, going way beyond just our grandfathers way of documenting an API. We have the language (Swagger & API Blueprint) to describe our APIs, lets begin providing more meaningful ways to engage with them as well.
If you would like to, or are already building any of these features I’m laying out, feel free to connect with me, and I'm happy to provide feedback anywhere during the design, development, and implementation—just let me know what you need.
I know I’m a demanding bitch in the API space, expecting people to do this work for me, but the space needs it. Thanks for building it! ;-)