# Paths and Operations — OpenAPI / Swagger

Source: https://www.skillbyai.com/en/openapi/p-operations

> Describe endpoints with paths, HTTP methods, operationIds, tags and summaries.

## 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.

![A vertical list of path bars, each with small coloured method badges attached to its right side.](assets/figures/openapi/section-2-map.svg) — Figure 2.1 — Paths grouping operations by HTTP method.

## Operations on an orders resource

Stable operationIds, tags and a shared path parameter.

```yaml
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.

**Quiz:** What is the operationId mainly used for?

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

*Answer:* Uniquely identifying an operation, for example as method names in generated code. operationIds are unique identifiers that tools use for naming and linking.