Glossary

OpenAPI

OpenAPI describes the contract of an HTTP API. It is neither the API itself nor a substitute for decisions about its business behaviour.

Short definition

A shared, machine-readable description of an HTTP interface.

The OpenAPI Specification (OAS) describes an HTTP API independently of any programming language. A JSON or YAML document can tell people and tools which URLs, HTTP methods, parameters, request bodies, and responses the API provides, as well as the security mechanisms or requirements declared by the contract.

The API itself is the running interface, while REST is an architectural style that may or may not shape its design. OpenAPI, by contrast, is a formal contract. It is useful only when it reflects the actual behaviour of the service and changes are managed as carefully as source code.

Use cases

What OpenAPI is used for

A well-maintained contract reduces guesswork between developers, integrators, and operations teams.

interactive endpoint documentation for integrating an online store, warehouse, or marketplace
validating the shape of incoming requests and returned responses
generating typed clients, test inputs, or starter server code
contract-first design, where the interface is agreed first, and code-first development, where the description is generated from the application
checking contract compatibility before publishing a new API version

Practical example

A contract for retrieving an order

A marketplace integrator knows in advance which identifier to send, what a successful response looks like, and how to distinguish a missing order from an invalid token. Both the server and client can validate this small part of the contract.

paths:
  /orders/{orderId}:
    get:
      operationId: getOrder
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Objednávka
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '404': { description: Objednávka nenalezena }

How it works

From an operation to a verifiable contract

The document brings interface rules together in a single version that people and tools can both use.

Document foundation Information about the API, servers, and global security defines the scope of the contract.
Paths and operations Paths and methods, such as GET /orders/{id}, describe specific operations.
Inputs and outputs Parameters, request bodies, responses, and schemas define the structure and meaning of the data.
Shared components Components reuse schemas, responses, or security schemes without duplication.
Change checks A validator, often run in CI, compares the document with the implementation; an incompatible change requires a managed transition.

Key concepts

What the contract consists of

The documented data shape and the actual meaning of the operation are equally important.

Schemas and examples

A schema defines expected types, required fields, and structure. An example helps integrators, but must not stand in for the rules or contain sensitive data.

Responses

Every significant outcome should have a documented HTTP status, headers, and body, including the error format.

Security schemes

The contract can specify an HTTP bearer token or an OAuth 2.0 flow, for example. The declaration alone does not configure permissions or secure verification.

Compatibility

Adding an optional field is usually less risky than removing one, changing its type, or making a new input mandatory. The rules followed by clients always matter.

Benefits and limitations

A more precise agreement does not automatically make for a high-quality integration.

Benefits

a single readable source for documentation, tests, and clients
earlier discovery of differences between the expected and actual data shape
reuse of schemas and consistent error responses
better assessment of compatibility before releasing a change

Risks

an outdated document creates false confidence
an overly broad schema loses its value for validation
a generated skeleton can obscure the need to design business rules
changing the contract without a transition period can break clients

Scope

A contract matters when an API lives beyond a single endpoint.

OpenAPI is particularly useful for public, partner, and team APIs, where multiple clients evolve independently of the server. It may provide less value for a small, one-off internal operation, but even then it is worth briefly documenting the input, response, and error.

The specification does not answer whether an order can be changed, how a timeout is handled, or whether an operation is idempotent. These properties must be explicitly designed, documented, and verified outside the documentation generator itself.

What to consider

Maintain the contract as part of the application.

A change should be checked not only for syntactic validity, but also for its impact on API users.

named and stable operationId values, data models, and errors
examples based on realistic but anonymised data
versioning and a deprecation period for incompatible changes
verifying both requests and responses in integration tests
clearly documented security, limits, and error behaviour

Common questions

Common misconceptions about OpenAPI

Is OpenAPI the same as Swagger?

No. OpenAPI is a specification. Tools originally associated with the Swagger name now commonly display or validate OpenAPI documents, or generate code from them.

Does an API have to be RESTful to use OpenAPI?

No. OpenAPI describes HTTP interfaces; their URLs and operations do not have to meet every REST principle.

Does a generated client replace manual integration testing?

No. A client may serialise data correctly, but it cannot guarantee service availability, permissions, business rules, or correct error handling.

Is adding a field always backward-compatible?

Not always. It depends on whether clients reject unknown fields, how the field is interpreted, and whether it is newly required.

How I use OpenAPI in practice

I treat an interface as a long-term agreement between systems.

For APIs and integrations, I address contracts, validation, error states, and the traceability of dependent synchronisation processes.

How I work with APIs and integrations Discuss your project without obligation