---
published: true
layout: post
title: OpenAPI Is Not the Thing
date: 2025-03-20T09:00:00.000Z
tags:
  - OpenAPI
  - HTTP
  - Standardization
  - Experience
image: https://kinlane-productions2.s3.amazonaws.com/algorotoscope-master/bf-skinner-feminist-pioneers.jpeg
---
A lot of attention gets placed on OpenAPI as a final output, without much understanding of the importance of OpenAPI being more about everything that goes into its creation. A complete OpenAPI doesn’t just magically appear and does everything you need to deliver an API, documentation, SDKs, and client. It takes work. It takes collaboration. It takes general HTTP and other standards knowledge. It takes specific domain knowledge. An OpenAPI is simply a negotiated contract between different stakeholders producing an API, while also considering and ideally negotiating over time what different stakeholders who are consuming an API will need. The OpenAPI is a representation of that work, and does not just magically appear from the cloud, a prompt, or via a GitHub search. Here are the things an OpenAPI provides that you will not get when just auto generating an OpenAPI.

- **Same Page** - Nobody producing your API or consuming an API is on the same page. 
- **HTTP Awareness** - Nobody producing your API will develop their awareness of HTTP.
- **Consumer Empathy** - Nobody is forced to have to explain and articulate to consumers.
- **Standardization** - The standards might be there, but nobody understands why they are.
- **Experience** - No connection to docs, sandbox, security, code gen, and other experiences.

People’s obsession with OpenAPI being the thing is very similar to people focusing on books, white papers, and this blog post being the thing. It is the output. It is the tangible thing people can see. They can’t see the process behind it. They can’t see the expertise behind it. So people tend to think the automatic creation of blog posts or OpenAPI is the thing. I am confident in saying that OpenAPI is not the thing. This doesn’t mean it isn’t important, or I’d say crucial. What I am trying to say is that you are all missing the importance of OpenAPI if you are just focused on it as an output. There is so much more to why Swagger and OpenAPI became a thing, and is being used by major API producers. OpenAPI is just a tangible accumulation of all the things happening that matter most when producing an API, and it will take work to produce in a way that adds value to your business, and to the business of your customers.