Darrel Miller has a thought provoking post on OpenAPI not being what he thought, shining a light on a very important dimension of what OpenAPI does, and doesn’t do in the API space. In my experience, OpenAPI is rarely what people think, and I want to revisit once slice of Darrel’s story, in regards to folks generally thinking OpenAPI (Swagger) as being all about API documentation. In 2017, the majority of folks I talk to think OpenAPI is about documenting your APIs–something that always makes me sad, but I get it, and is something I regularly work to combat this notion.
First, and foremost, OpenAPI is a bridge to understanding and being able to communicate around using HTTP as a transport, and our greatest hope for helping developers learn their HTTPs and 123s. I meet developers on a regular basis who are building web APIs, yet do not have a firm grasp on what HTTP is. Hell, I’ve had a career dedicated to web APIs for the last seven years, and I’m still developing my grasp on what it is, learning new things from folks like Erik Wilde (@dret), Darrel Miller (@darrel_miller), and Mike Amundsen (@mamund) on a regular basis. In the API game, you should always be learning, and the web is the center of your existence at the moment as a software engineer, and should be the focus of what you are learning about to push forward your knowledge.
Darrel has a great line in his post where he has “a higher chance of convincing developers to stop drinking Mountain Dew than to pry a documentation generator from the hands of a dev with a deadline.” Meaning, most developers don’t have the time or interest to learn about what OpenAPIs, or can do for them in their busy world, they just want the help delivering documentation–a very visual representation of the work they’ve done, and is something they can demonstrate to their boss, partners, and customers. Most developers aren’t spending the time trying to know and understand everything API, thinking deeply on the subject like Darrel and I are doing. Most don’t even have time to read our blog posts. A sad fact of doing business in the tech space, but is something us in charge of API standards and tooling, or even selling API services should be aware of.
You see an essence of this with API code generators, and API testing from OpenAPI. Although in much lesser quantities than API documentation enjoys. Developers just want the assist, they really don’t care whether it is the right way of doing things, or the wrong way, and how it fits into the bigger picture. API developers just want to get their work done, and move on. It is up to us analysts, standards shepherds, and API service providers to help educate, illuminate, and incentivize developers to get over their limiting views on what OpenAPI is and/or develop the next killer tooling that helps make their lives insanely easier like Swagger UI did for API documentation. We need to learn from the impact this tooling has made, and make sure the other lifecycle solutions we are delivering speak in similar tones.
If you are reading this piece, and are still in the camp of folks who still see OpenAPI as Swagger UI, don’t feel bad, it is a common misconception, and one that was exacerbated by the move from Swagger to OpenAPI. My recommendation is that you begin to look at OpenAPI independent of any tooling it enables. Think of it as a checklist for your HTTP learning, sharing, and communication across your API development team. It shouldn’t be just about delivering documentation, code, tests, or anything else. OpenAPI is about making sure you have the HTTP details of your API delivered in a consistent way, across not just a single APIs, but all the APIs you are delivering. OpenAPI is the bridge to where you are now with your API operations, to where you should be when it comes to the definition, design, deployment, management, and delivering sustainable contracts around the digital assets you are serving up internally, with partners, and 3rd party developers. It may see like extra work to think about it this way, but it is something that will save you time and money down the road.
