Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Paths, Schemas and Components

OpenAPI Paths and Operations: Describing Endpoints

Learn how the OpenAPI paths object works: path items, HTTP methods, path templates, operationId, summary, tags, deprecation and how to design clean endpoints.

The paths object is the heart of an OpenAPI document. Each key is a URL path, each path holds the HTTP methods it supports, and each method is an operation with its own parameters, request body and responses. Everything else in the specification exists to describe these operations accurately.

Anatomy: paths, path items, operations

flowchart TD
  P["paths"] --> I1["/pets  (path item)"]
  P --> I2["/pets/{petId}  (path item)"]
  I1 --> O1["get  (operation)"]
  I1 --> O2["post (operation)"]
  I2 --> O3["get"]
  I2 --> O4["put"]
  I2 --> O5["delete"]
  O3 --> D["parameters, requestBody, responses,<br/>security, tags, summary, operationId"]

A path item groups all operations for one URL; each operation is a method plus its details.

YAML
paths:
  /pets:
    summary: Pets collection
    description: All pets in the store.
    parameters: []          # shared by every operation on this path
    get:
      operationId: listPets
    post:
      operationId: createPet
  /pets/{petId}:
    get:
      operationId: getPet
    put:
      operationId: replacePet
    patch:
      operationId: updatePet
    delete:
      operationId: deletePet

Supported operation keys in 3.1: get, put, post, delete, options, head, patch and trace. OpenAPI 3.2 adds more ways to describe additional methods, such as QUERY; check your tool's support first.

Path rules

  • Every path starts with / and is appended to the server URL, so do not repeat the base path (/v1) in every key.
  • Templating uses braces: /pets/{petId}. Every template variable needs a path parameter (see parameters).
  • Do not put the query string in the path. /pets?limit=10 is wrong; describe limit as a query parameter.
  • Two paths must not differ only by a variable name: /pets/{id} and /pets/{petId} are ambiguous together.
  • Concrete paths win over templated ones: /pets/search is matched before /pets/{petId}.
  • Paths are case sensitive and a trailing slash is a different path. Pick a convention (lowercase, no trailing slash) and keep it.

What an operation contains

Field Meaning
summary One short line shown in lists.
description Longer Markdown text.
operationId Unique, case-sensitive id; becomes a function name in generated code.
tags Groups for documentation.
parameters Inputs in the path, query, headers or cookies.
requestBody The data sent with POST, PUT, PATCH.
responses What can come back (required).
security Overrides the global security requirements.
deprecated true marks it as going away.
servers Overrides the base URL for this operation.
callbacks Requests the server will send later.
YAML
get:
  operationId: listPets
  summary: List pets
  description: |
    Returns pets newest first. Use `limit` and `cursor` to page.
  tags: [pets]
  deprecated: false
  responses:
    "200":
      description: A page of pets

Which method for which job?

Method Typical use Has request body? Safe Idempotent
GET Read a resource or list No Yes Yes
POST Create, or run an action Yes No No
PUT Replace a whole resource Yes No Yes
PATCH Partially update Yes No No (depends)
DELETE Remove Usually no No Yes
HEAD / OPTIONS Metadata only No Yes Yes

In OpenAPI 3.0 and 3.1 a GET, HEAD or DELETE request body is undefined in meaning, so the specification says requestBody is only allowed where the HTTP specification defines the semantics. Avoid sending a body with GET. See the REST guidance in REST API design.

operationId: small field, big effect

Generators turn operationId into method names (client.listPets()), and test tools use it as an identifier. Follow a naming scheme: a verb plus the resource in camelCase (listPets, getPet, createPet, deletePet). It must be unique across the whole document.

Deprecating an operation

YAML
/pets/by-name:
  get:
    operationId: findPetByName
    deprecated: true
    description: Use `GET /pets?name=` instead. Removed on 2026-06-01.

Documentation tools strike the operation through, and generators add deprecation attributes to the generated method.

Walk the paths: a lister with a problem finder

This stand-in lists operations and spots two of the most common mistakes in the paths object: a missing operationId and ambiguous templated paths.

Python Stand-in: inspect paths and find ambiguous templates

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.

Path-level and operation-level overrides

A path item may carry parameters, servers, summary and description that apply to every operation under it. An operation can add to or override them. This avoids repeating petId on GET, PUT and DELETE:

YAML
/pets/{petId}:
  parameters:
    - name: petId
      in: path
      required: true
      schema: { type: integer, format: int64 }
  get:    { operationId: getPet,    responses: { "200": { description: OK } } }
  delete: { operationId: deletePet, responses: { "204": { description: Deleted } } }

Parameters are unique by the pair (name, in); an operation parameter with the same pair replaces the path-level one.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What must every path key in the paths object start with?

    Path keys are relative to the server URL and always begin with a slash.
  2. 2. Which field is required in every operation?

    responses is the only required field of an operation; operationId is strongly recommended.
  3. 3. Why is /pets/{id} together with /pets/{petId} a problem?

    Paths that differ only by variable names match the same URLs, which the specification forbids.
  4. 4. Where should the query string ?limit=10 be described?

    Query strings are never part of the path key; use in: query parameters.
  5. 5. What does deprecated: true do?

    It is a signal for readers and generators; the operation still exists.

Summary

  • paths maps URL paths to path items; each path item maps HTTP methods to operations.
  • Paths start with /, use for variables and never contain query strings.
  • An operation needs responses; operationId, summary and tags make it usable by tools.
  • Shared parameters can sit on the path item and be overridden per operation.
  • Mark retiring operations with deprecated: true and explain the replacement.

Next: Parameters: path, query, header and cookie