As I profile more APIs for my APIs.json work, I keep coming across GitHub repositories that are dedicated to managing API providers OpenAPIs. I am gathering these along the way so that I can publish a story about how these API providers manage their OpenAPIs using GitHub, but I’d also like to eventually provide a blueprint for companies to follow when doing this. Having your OpenAPIs well managed on GitHub is pretty beneficial to your operations as an API producer, but also can go a long way to helping enable your consumers. But, before I get to these stories and projects, I wanted to document the approach of a single API producer — Digital Ocean — and document their rather sophisticated approach to using GitHub to manage their OpenAPI.
If an API provider uses GitHub to manage their OpenAPIs I take notice, but most of them are just a single repository with a single OpenAPI, or many OpenAPIs that have been broken up by some bounded context. Digital Ocean takes things a bit further, and breaks their OpenAPI into common and individual resources, but then also further breaks down by OAS objects operations, responses, models, and examples. They have a master OpenAPI, but it is basically a path and verb scaffolding, with the rest of the technical details broken down into separate folders and files, which can be assembled using a single MAKE file. I like the approach. As I have written about before, I prefer modular OpenAPI over monolithic OpenAPIs, but their approach has some differences from what I am doing with APIs.json, I am not sure I want to emulate.
I like the atomicity of Digital Ocean’s approach to managing their OpenAPI. It allows you to manage everything separately, but then assemble into a single OpenAPI using a MAKE file. You can also run alternate commands to generate a Postman Collection, or HTML documentation—both of which I like a lot. I like the bundling and publishing as collections and documentation for consumers. I like keeping things modular and separate and then bundling for specific purposes like powering clients and documentation. However, I’d say for my purposes, I find having smaller, complete OpenAPIs representing separate bounded contexts, rather than just a big bucket of Lego bricks. I am not sure though, which is why I want to write about, then simmer and think upon it as I am managing my growing archive of APIs.json and OpenAPIs.
While I think Digital Ocean’s approach would work well for a single API producer, I am working across many. This really is the big difference. The other big difference is I am defining artifacts for across API operations, not just the machine-readable artifacts defining the technical surface area of APIs. This is the common mistake I see most API providers making-—they focus only on the technical details. I am organizing the business and technical details across many API providers. There are plenty of lessons at the lower levels of individual API operations for me to learn from, but I am managing artifacts at a different scale. Regardless, the Digital Ocean GitHub repository is important for me to add to the notebook here and bookmark for future reference. I will work on stories about other API providers who use GitHub to manage their OpenAPI, develop my blueprint for how I’d recommend API providers use GitHub to manage their OpenAPI, then I will re-evaluate my own Git-driven approach for APIs.json.
