I’ve been pushing forward conversations around my Human Services Data API (HSDA) work lately, and hitting some friction with folks around the finer technical details of the API. I feel the friction around these API conversations could be streamlined with OpenAPI, but with most folks completely unaware of what OpenAPI is and does, there is friction. Then for the handful of folks who do know what OpenAPI is and does, I’m seeing the common misconceptions about what they think it is slowing the conversation.
Let’s start with the folks who are unaware of what OpenAPI is. I am seeing two main ways that human services data vendors and implementations have conversations about what they need: 1) documentation, and 2) code. The last wave of HSDA feedback was very much about receiving a PDF or Word documentation about what is expected of an application and an API behind it. The next wave of conversations I’m having are very much here are some code implementations to demonstrate what someone is looking to articulate. Both very expensive waves of articulating and sharing what is needed for the future, or to develop a shared understanding. My goal throughout these conversations is to help folks understand that there are other more efficient, low costs ways to articulate and share what is needed–OpenAPI.
Beyond the folks who are not OpenAPI aware, the second group of folks who see OpenAPI as a documentation tool, or code generation tool. Interestingly enough a vantage point that is not very far evolved beyond the first group. Once you know what you have, you document it using OpenAPI, or you generate some code samples from it. Relinquishing OpenAPI to a very downstream tool, something you bring in after all the decisions are made. I had someone say to me, that OpenAPI is great, but we need a way to be having a conversation about each specific API request, the details of the that request, with a tangible response to that request–which I responded, “that is OpenAPI”. Further showing that I have a significant amount of OpenAPI education ahead of me, before we can efficiently use it within these conversations about moving the industry specification forward. ;-(
The reasons OpenAPI (fka Swagger) began as documentation, then code generation, then exploded as a mocking, and API design solution was the natural progression of things. I feel like this progression reflects how people are also learning about the API design life cycle, and in turn the OpenAPI specification itself. This is why the name change from Swagger to OpenAPI was so damaging in my opinion, as it is further confusing, and setting back these conversation for many folks. No use living in the past though! I am just going to continue doing the hard work of helping folks understand what OpenAPI is, and how it can help facilitate conversations about what an API is, what an API should do, and how it can be delivering value for humans–before any code is actually written, helping make sure everyone is on the same page before moving to far down the road.
