OpenAPI specification: describing an API so machines can read it

An OpenAPI specification is a machine-readable description of an HTTP API: its endpoints, parameters, request and response shapes, authentication and errors, written in YAML or JSON to a published standard. It is the format formerly called Swagger, and it has become the default way APIs describe themselves.

The reason to write one is not documentation for its own sake. It is that a single accurate description drives several things at once — reference docs, client libraries, a try-it console, request validation and contract tests — and each of those otherwise drifts away from the API separately.

What it buys you

• Generated reference documentation that cannot describe endpoints the API does not have.
• Client libraries in several languages without hand-writing any of them. Quality varies by generator, and even a mediocre generated client beats a hand-written one that nobody updates.
• A try-it console, which is the fastest route from a developer reading to a developer succeeding.
• Request and response validation, in tests or at the edge, catching mismatches before customers do.
• Contract tests: the specification becomes the agreement between the team building the API and the teams consuming it.
• Mock servers, so a client can be built before the API exists.

Design-first or code-first

Two approaches with a real trade-off. Design-first writes the specification before the implementation, reviews it, then builds to it — better for APIs with external consumers, because the interface gets discussed while changing it is still cheap. Code-first generates the specification from annotations in the implementation, which guarantees the two match and tends to produce a specification shaped by the code rather than by the consumer's needs. Design-first is the better default for anything customers will build against; code-first is a reasonable choice for internal APIs where speed matters more than interface quality.

Whichever approach you pick, validate the specification in continuous integration and test the real API against it. A specification that has quietly diverged from the implementation is worse than none, because everything downstream — clients, docs, mocks — is now confidently wrong. The check costs one build step.

Writing one that stays useful

1. Describe every response you actually return, including the errors. Specifications that document only the happy path generate clients that break on the first 422.
2. Use components and references for repeated shapes rather than copying them. Copies diverge.
3. Give every operation a stable operationId — generators use it to name methods, and changing it renames somebody's function.
4. Include realistic examples. Generated documentation is only as good as the examples in the source, which is the point made in api documentation.
5. Version the specification alongside the API and keep old versions published.
6. Keep descriptions written for a human. The specification is a source for docs, not just a schema.

Where it fits

Ettex API is described by the conventions in rest api, with the surrounding documentation practices in api documentation and the limits in rate limiting.

One honest note: whether a published OpenAPI document exists for a given part of Ettex, and at what version, belongs in the reference rather than in an article — this piece describes the format and how to use it well, not a claim about current coverage.