OpenAPI is the standard machine-readable description of a REST API (endpoints, parameters, schemas, errors) from which typed client libraries, documentation and API tool collections can be generated.
An OpenAPI document, written in YAML or JSON, describes a REST API precisely enough for software to work from it: the servers, every path and operation, the parameters and request bodies, the response schemas for success and for each error, and the authentication scheme. The specification grew out of Swagger and is maintained by the OpenAPI Initiative; version 3.1 aligned its schemas with JSON Schema.
From one file, tools can generate typed clients in TypeScript, Python, Java and many other languages, import the API into Postman or Insomnia, validate requests and responses in tests, run mock servers, render reference documentation and flag breaking changes between versions. For a small API a generated client can replace official SDKs entirely, and it stays current by construction when the file is versioned with the API. The file is also the most useful artefact an AI coding assistant can read to integrate an API correctly.
What a schema does not capture is behaviour: when to retry, how idempotency works, how webhooks are signed. Those still need the prose documentation.
Example
A hypothetical team generates a TypeScript client from an SMS provider's file. The compiler now rejects code that forgets a required field, and the message type shows that a response includes the segment count and the price, so the team's cost tracking is written against real fields rather than guesses.
Common mistakes
- Generating a client once and never regenerating it, so that it drifts from the API.
- Hand-editing generated code, which the next generation overwrites.
- Pointing tools at a stale downloaded copy instead of the published file.
At SMSMeteor: the API is described in OpenAPI 3.1, published at /docs/openapi.yaml and versioned with the API. Samples, including cURL, Python, Node, PHP and Go, are on the SDKs page. A test key answers like a live key without sending or billing, so a generated client can be exercised end to end before any money is deposited.
