Skip to main content
  1. What is OpenAPI for?

What is OpenAPI for?

OpenAPI describes itself as a "API description format for REST APIs". That is correct, but it does not address the use cases and answer the question "what is OpenAPI for". That's what this post is about.

I think it's better to think of OpenAPI as the written language for APIs. If you don't have your API written down it is folk tale -- a little different each time you tell the story, not concrete, and never fully understood by any one person.

OpenAPI is a written language that lets people talk about the APIs they build and consume. By standardizing the terminology, syntax and symbols we use to discuss APIs, OpenAPI helps everyone talk about the same thing. If you do not write down the API, you can only have a fuzzy conversation about its behavior -- "send this", receive "that". Writing it down is the first step to going pro.


When you write an OpenAPI description that describes an API that already exists in the real world, we call it "documentation". Your API consumers build different kinds of products than you and have their own goals and terminology. Good docs help translate their intent to your API ie "send a package" to post /shipment. These docs can be shared with internal and external consumers. Good docs helps prospective consumers discover your API and start using it without having a direct relationship with your team.

Documentation is also a list of promises about your API behavior. If the promise is in your documentation, consumers expect you to keep it. If your API does not behave the way your docs claim it does -- you loose credibility with consumers quickly.


You can write about imaginary worlds just as easily as you can write about the real one. OpenAPI allows you to design APIs and show them to your stakeholders before building anything. Imagine if an architect was not allowed to show blueprints to their clients and could only talk about the building in their imagination? The feedback the client could give would be very poor because they aren't seeing the exact same thing as the architect. The same is true for APIs.

APIs are difficult to change once they ship. The best API teams understand that and spent time up-front to show their consumers what they're planning to build in written form. You can even build an API-mock so people can feel your API (for real) -- like an architect showing a VR model.

Design your APIs on paper, use OpenAPI to do it. This gives consumers information at the resolution required to give great feedback.


APIs are promises. When those promises are vague and fuzzy it is impossible to know for sure if your team is keeping its end of the promise. A promise cannot be kept unless it is specific and written down. There are two kinds of promises OpenAPI can help you keep:

  • The API works the way the documentation says it does. When a consumers calls your API, it gives me what you say it will. This is usually called Contract testing
  • The API is stable -- there are no breaking changes, some versioning strategy is being followed. If a consumer's integration worked yesterday, it should continue to work tomorrow. Read about testing API changes

Written language is a powerful tool. OpenAPI lets you talk about your API with your team, consumers and other stakeholders. People get caught up on "design-first" vs "code-first", code generation and other topics that do not really matter. Here's what matters:

Does your team talk about the design of the APIs you are building, before shipping them? Do you get feedback (like an architect with their draft blueprints) from a few consumers before you ship?

πŸ‘† If you can just pull that off, you are doing the most important parts of working API-first