OpenAPI Specification

The OpenAPI Specification is a document that describes how programs can talk to each other through an API, written in a very fixed format—basically an instruction manual for the API. Think of a restaurant menu: not a handwritten one, but a menu where the dish names, ingredients, prices, and ordering method are all written in a standard layout that anyone can read the same way.

Why does this format matter so much? Because it's not humans but computer programs that need to read this document and act on it automatically. Humans can figure out vague instructions from context, but programs can't. When a document is written using the OpenAPI Specification, programs built by different companies and different developers can look at the same set of rules and automatically figure out how to connect to each other. Recently, AI agents have also started reading these documents to write API-calling code on their own or to find and use the functions they need.

To put it another way, it's like the whole world agreeing to use the exact same application form format instead of every country's embassy making its own form in its own language. That way, anyone can look at the form and immediately know what goes where.

In articles, you'll usually see phrasing like "this service has released its OpenAPI Specification." That doesn't mean the service built a brand-new API—it means the service organized the features and calling methods of an API that already exists into a standardized document and made it public. API and OpenAPI Specification are easy to mix up but are different things: the API is the actual functionality, while the OpenAPI Specification is the standardized document that describes that functionality.

Check the developer documentation page of a service you use regularly for a link named something like openapi.json, openapi.yaml, or swagger.json. If you find one, paste its address or contents into a coding assistant AI and ask it to "write code that calls a specific function based on this API spec." You'll get to see the AI read the document and generate working code right away.