Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 37 ยท Getting Started

What Is OpenAPI? Describing HTTP APIs for Humans and Machines

Learn what OpenAPI is, why a machine-readable API description matters, what you can build from one document, and how it fits next to REST and JSON.

Every HTTP API has a hidden contract: which URLs exist, which methods they accept, which data they expect and what they send back. In most projects that contract lives in somebody's head, in a wiki page that went stale months ago, or in the source code of the server. OpenAPI is a way to write that contract down in one structured file that both people and programs can read.

An OpenAPI document is plain JSON or YAML. It does not contain any server logic. It describes an API: its endpoints, its inputs and outputs, its error shapes and how callers prove who they are. Because the description follows a strict format, tools can read it and do real work: draw documentation, generate client libraries, validate requests, build mock servers and run tests.

About this track. OpenAPI, Swagger UI, Redocly, openapi-generator and friends are tools you install on your own machine, and they cannot run inside this website. Everything that touches them is described as precisely as possible (commands, menus, file contents) and no output is invented. The live examples on these pages are small Python stand-ins that read an OpenAPI document and do the same kind of work, so you can see the ideas run. Each stand-in is labelled.

The problem OpenAPI solves

Imagine a team building a pet-store service. The backend developer adds GET /pets/{id}. The mobile developer has to guess the response shape. The QA engineer writes tests from a chat message. A partner company asks for "the docs", and someone exports a PDF that is outdated a week later.

A written contract fixes this because it becomes the single source of truth:

  • The backend implements what the document says (or the document is produced from the backend).
  • The frontend and mobile teams generate typed clients from it.
  • QA validates real traffic against it.
  • Technical writers publish it as interactive documentation.

A first look at an OpenAPI document

Here is a complete, tiny document in YAML. Do not worry about every line yet; the next lessons explain each part.

YAML
openapi: 3.1.0
info:
  title: Pet Store
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        "200":
          description: A list of pets

It says: "this API is called Pet Store, version 1.0.0, and it has one endpoint: GET /pets, which can answer with status 200".

Machines can read it

Because the structure is predictable, a program can walk the document. This stand-in does what a documentation tool does at its core: list every operation.

Python Stand-in: list the operations of a document

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Real tools do the same walk and then render pages, generate code or run checks.

What you can build from one document

One document, many outputs

Documentation Interactive reference pages
Client SDKs Typed libraries in many languages
Tests Contract checks in CI
Mock servers Fake API before the backend exists
1 / 2

Where OpenAPI sits next to REST

OpenAPI is not REST and it is not a framework. It is a description format. It is most often used for REST-style JSON APIs (see REST API design), but it can describe any HTTP API: RPC-style endpoints, file uploads, even webhooks. It does not describe GraphQL (which has its own schema language) or gRPC (which uses Protocol Buffers).

flowchart LR
  D["OpenAPI document<br/>(YAML or JSON)"] --> DOC["Docs site"]
  D --> SDK["Client / server code"]
  D --> TEST["Contract tests"]
  D --> MOCK["Mock server"]
  S["Real API server"] -. "must match" .- D

The document is the hub; every tool reads it, and the real server must match it.

Two ways to work

  • Design-first: write the document first, review it with everyone, then build the server and clients from it. The track overview lists the later chapters on this workflow.
  • Code-first: write the server code with annotations and let a library produce the document. Quick to start, but the contract can drift from your intent.

Both are valid. This track teaches the format so that you can read and write the document by hand, which makes you effective with either approach.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is an OpenAPI document?

    OpenAPI describes the API (paths, inputs, outputs, security). It contains no server logic.
  2. 2. Which of these formats can an OpenAPI document be written in?

    The specification allows JSON and YAML; they carry exactly the same data.
  3. 3. Which task is NOT something you can typically do from an OpenAPI document?

    Tools can generate server stubs, but the real business logic is still yours to write.
  4. 4. OpenAPI is mainly used to describe which kind of API?

    OpenAPI is built around HTTP: paths, methods, status codes and media types.

Summary

  • OpenAPI is a standard, machine-readable way to describe an HTTP API.
  • The description is a JSON or YAML document with no server logic in it.
  • One document can drive docs, SDKs, mocks, tests, validation and gateways.
  • It is not REST itself and does not cover GraphQL or gRPC.
  • You can work design-first (document, then code) or code-first (code, then document).

Next: OpenAPI, Swagger and the version history