OpenAPI specification

The OpenAPI specification is a standard format for describing, in one file, everything an API accepts and returns. It was earlier called the Swagger specification, after the tools in which it began. An API, or application programming interface, is the agreed way in which one program asks another program to do something. The OpenAPI file is the exact written description of that agreement, so that both people and programs can read it.

Here is how it works in general. The team that owns an API writes one file, in a simple text format called YAML or JSON. For each endpoint, the address that a request is sent to, the file lists what the request must contain: which fields, of what type, which ones are required, and the allowed values. It lists every reply the API can send, with its status number, such as 200 for success or 404 for "not found", and the fields in each reply. It also says how a caller must prove who it is, for example with a key. Because the file follows one standard, tools can read it. An API development platform turns it into documentation pages and a screen for trying each request. Other tools generate client code, the code that a caller's program uses to send requests. API testing tools send many requests and check every reply against the file. An API gateway, the software in front of the API, can block requests that do not match it.

Many teams now write the file first, before any code, and agree it with the teams that will call the API. This is called design-first.

Take, for example, a courier company that lets online shops book pickups through its API. It publishes an OpenAPI file, and a shop's developer generates the booking code from it instead of copying every field by hand.

Consider a state transport department's ticketing app, built by two vendors. One vendor builds the API and the other builds the app. Both work from the same OpenAPI file, so the app can be built before the API is finished.

Say a travel company gives an AI agent access to a hotel-booking API. The agent reads the OpenAPI file to learn which requests exist and which fields each one needs, and then calls the API correctly.

How is an OpenAPI specification different from ordinary API documentation? Ordinary documentation is written for people, in sentences and examples, and it can fall out of date without anyone noticing. An OpenAPI file is written for programs as well as people. Tools can check it, generate code from it and test the API against it. Good documentation pages are now often produced from the file itself.