OpenAPI

Programs constantly exchange data over the internet. A weather app, for example, fetches the forecast from an external server. For this to work, the server must describe somewhere exactly which requests it understands and what it sends back. That’s precisely what OpenAPI is for: a uniform format in which such a description is written down. The file is structured so that both humans can read it and programs can automatically evaluate it. You can think of it as a very precise menu: it lists what can be ordered, what information must be provided, and what ends up on the plate afterward.

Why a menu for servers saves so much work

Before such standards existed, companies described their interfaces in plain text documents. These texts quickly became outdated because no one maintained them. Developers then had to guess or try things out to figure out what a server expected. This cost days and led to errors that only surfaced once things were already running in production.

An OpenAPI file, by contrast, is machine-readable. From it, a documentation website, testing tools, and even ready-made program code can be generated automatically. If the interface changes, you change the file once, and everything else is regenerated. This reduces misunderstandings between teams working on different ends of the same connection.

An important distinction: OpenAPI is not a program and not software. It is merely an agreed-upon format for descriptions. The actual work is still done by the server and the tools that read the file.

What’s inside such a description file

An OpenAPI file is written in YAML or JSON. These are two simple text formats in which information is laid out as lists and pairs of labels and values. Both look roughly like a very neatly indented bullet-point list. The advantage: a program can reliably parse this structure without needing to understand sentences.

The core consists of so-called paths. A path is an address on the server, such as “/weather/today”. For each path, it’s specified which actions are allowed: retrieving data, creating new data, deleting existing data. Then there are the parameters, i.e., the information the caller must provide, such as a postal code.

The file also describes the responses. It specifies which fields come back and whether they contain numbers, text, or boolean values. Error cases are also listed, such as “location not found”. Another section governs authentication, i.e., whether an access key is required. Together, this forms a complete instruction manual without any running prose.

From developer docs to a tool for language models

Anyone who opens the documentation of a larger online service often lands on a page generated from an OpenAPI file. It can be recognized by expandable lists of addresses and a button for trying things out directly. This presentation often comes from a tool called Swagger UI. Swagger, incidentally, was the earlier name of the format, before it was handed over to an open organization in 2015 and renamed OpenAPI.

In recent years, a new use case has emerged. For a chatbot to do something other than write text, it needs to be able to call external services. To enable this, the model is given an OpenAPI description, from which it reads which functions it is allowed to use. This lets an AI independently search for a flight or create a calendar entry.

A common misconception is that an OpenAPI file guarantees the server will actually behave that way. It does not. The description can be outdated or simply wrong if nobody maintains it. That’s why many companies automatically check whether the description and the actual behavior still match.