Paths, operations and parameters

Paths and parameters are the bulk of every API description.

Each key under paths is a path template relative to the server URL, with variables in braces: /books/{bookId}. Under it, keys are HTTP methods (get, post, put, patch, delete...), each an operation object.

Useful operation fields:

operationId: a unique name like getBook. Code generators use it as the method name, so pick stable, descriptive ids.
summary and description for docs; tags to group operations.
parameters, requestBody, responses, security, deprecated: true.

Parameters have a name, an in location and a schema:

in: path: part of the URL template. Path parameters must always be required: true.
in: query: ?limit=20. Arrays and objects are serialized according to style and explode (default for query: form, exploded, so ?tag=a&tag=b).
in: header: custom headers such as X-Request-Id. Do not describe Accept, Content-Type or Authorization as parameters; they are covered by content and security schemes.
in: cookie.

Parameters shared by all operations of a path can be listed at the path level. Each operation's parameters are identified by name plus in.

Path templates must not overlap ambiguously: /books/{id} and /books/{isbn} are the same template and invalid together.

Example

paths:
  /books/{bookId}:
    parameters:
      - name: bookId
        in: path
        required: true            # always required for path params
        schema: { type: string }
    get:
      operationId: getBook
      tags: [books]
      summary: Get one book
      parameters:
        - name: include
          in: query
          schema:
            type: array
            items: { type: string, enum: [author, reviews] }
          # serialized as ?include=author&include=reviews
        - name: X-Request-Id
          in: header
          schema: { type: string, format: uuid }
      responses:
        '200': { description: The book }
        '404': { description: No such book }

Remember

Path templates use {name}; path params are always required
operationId becomes the method name in generated SDKs
Parameters live in path, query, header or cookie
Don't model Content-Type, Accept or Authorization as parameters

Watch out for

Forgetting required: true on a path parameter, which makes the document invalid.

Check yourself

Why does `operationId` deserve a carefully chosen, stable name?

Official docs: learn.openapis.org/specification/parameters.html

Example

Remember

Watch out for

Check yourself

Builds on

Unlocks