I am building on my conversation with Abhinav Asthana (@a85), the Co-founder and CEO of Postman, around how we can simplify the API documentation we are providing to our API consumers. As part of my work to profile the 50+ stacks of APIs I list on my home page, I am playing with different ways of listing APIs, sharing the valuable endpoints available within, and other key aspects with users. All this work is being driven by APIs.json, and Open API Spec listings.
First I've rewritten my main API listing page using Liquid, running in Jekyll, which uses a _data folder full of APIs.json, and OpenAPI Specs published as part of each of my API life cycle, or API stack research. To operate, this listing just mounts the _data folder, and loops through all APIs.json files it contains, then parses each property present, giving special attention to OpenAPI Spec, and API plan formats.
Liquid + Jekyll, running on Github Pages gives me a simple, static way of representing the machine readable indexes I generate for any of my research areas using APIs.json, OpenAPI Spec, and my new API plan format. Jekyll gives me the entire contents of the API definitions I'm storing in my _data folder, as a single Liquid object which I can loop through, to generate the static HTML for my listing of APIs. Using this approach gives me a machine readable index of all the moving parts of any single, or multiple API collection.
The list of SMS APIs in this research is pretty verbose. I'm not even listing out the parameters, headers, and other details of each API, and the listings are pretty involved--further backing up Abhinav thoughts around simplifying the API documentation that we are generating. To help me push forward my Liquid skills, and the possibilities around breaking up the properties of each API defined using APIs.json, I took the same code and generated a separate, trimmed down version which only shows the APIs overview, and the details of their API plans, leaving out the details of each API endpoint.
While the static approach to generating HTML, using Liquid, Jekyll, and APIs.json, OpenAPI Spec, and API plan, has given me a lot of control, and I will keep pushing forward a toolbox of Liquid, Jekyll + JSON modules, I wanted to also push forward a JavaScript solution as well. Using Jquery, I basically recreated what I was doing with Liquid, giving me JavaScript array containing the APIs.json index of APIs. Now I know I can loop through, and share all the API details just as I listed above, but using JS I wanted to go beyond the Liquid representation, and make smaller, more embeddable API documentation solutions, that wouldn't be bound to a Jekyll site, if you didn't want them to be.
In my SMS research, I am profiling nine separate APIs, which each have its own APIs.json indexing each of the APIs, there is also a root APIs.json for the SMS research, which includes each of the sub API collections. I wanted to start here, and share a simple list of the API endpoints contained within each collection.
This gives me a nice, potentially human readable, list of the API endpoints available within any single API collection. I wanted to see what else I could do, and instead of using each APIs.json collection as the anchor point, I focused on the tags that were being applied to each API, within its Open API Spec, grouping all the endpoints by tag.
This gives me to quick, alternate vantage points of my API collections. While I like browsing the entire collection in detail via the main page, I can see the potential in understanding these resources on a new level, when I break them down by provider, or tags applied. One thing this brought to the surface for me, is how poorly, and inconsistently some of the API definitions are, but once I clean up the summaries and tags across these APIs, I'm thinking it could be some pretty powerful JuJu.
Ok, so WTF am I doing here? Why does it matter? I am decoupling the benefits that API definition driven, interactive documentation like Swagger UI, Apiary, and Lucybot Console have brought us. None of this is functional like Swagger UI is, I am just focusing on the decoupling of the surface area of any API, or collections of API, next I will play around with making things minimally interactive, like being able to make a simple GET call for an API, or maybe a POST as well--it will come with time.
I want to see some simple, embeddable, and easy to read and use API documentation, which could potentially have ALL the moving parts of an API, or a collection of APIs, but might also give you a sub, or cross section of the details of the API(s), and the value that is contained within. Not sure where all of this is going, I just wanted to play with Liquid and JavaScript driven APIs.json tooling, while also thinking further about what Abhinav and I talked about. Eventually I'd love to see a wealth of open, API definition driven modules, that API providers can use across their portals, but also API service providers like Abhinav can use in their API tooling, like Postman.
