Paths and Operations

Endpoints and what you can do with them

The paths object maps relative paths (appended to the server URL) to path items, each containing operations keyed by HTTP method: get, post, put, patch, delete, head, options and trace. Path templates use braces for path parameters: /orders/{orderId}/items/{itemId}. Each operation should have a summary (short, shown in lists), a description (longer, Markdown), tags for grouping in documentation, and an operationId: a unique, stable identifier such as getOrder or createOrder that code generators use as method names, so choose them carefully and do not change them casually. Parameters shared by all operations on a path can be declared once at the path-item level. Mark retiring operations with deprecated: true. Paths must be unique after templating: /orders/{id} and /orders/{orderId} are considered the same path and conflict. Keep paths noun-based and consistent, following your API style guide.

Paths and operations

Each path holds several operations, one per HTTP method.

Operations on an orders resource

Stable operationIds, tags and a shared path parameter.

paths:
  /orders:
    get:
      tags: [Orders]
      summary: List orders
      operationId: listOrders
      responses:
        '200': { $ref: '#/components/responses/OrderPage' }
    post:
      tags: [Orders]
      summary: Create an order
      operationId: createOrder
      requestBody: { $ref: '#/components/requestBodies/NewOrder' }
      responses:
        '201': { $ref: '#/components/responses/OrderCreated' }
        '422': { $ref: '#/components/responses/ValidationProblem' }

  /orders/{orderId}:
    parameters:                        # shared by all operations below
      - $ref: '#/components/parameters/OrderId'
    get:
      tags: [Orders]
      summary: Get an order
      operationId: getOrder
      responses:
        '200': { $ref: '#/components/responses/OrderBody' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      tags: [Orders]
      summary: Cancel an order
      operationId: cancelOrder
      deprecated: true
      description: Use POST /orders/{orderId}/cancellation instead.
      responses:
        '204': { description: Cancelled }

operationIds become method names

Generated SDKs turn listOrders into client.listOrders(). Renaming an operationId is a breaking change for SDK users even if the HTTP API is unchanged.

Quick check: What is the operationId mainly used for?

• Choosing the HTTP method
• Setting the server URL
• Uniquely identifying an operation, for example as method names in generated code
• Defining security