> For the complete documentation index, see [llms.txt](https://eazyapi-1.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://eazyapi-1.gitbook.io/docs/open-api-guide/paths-and-operations.md).

# Paths and Operations

In OpenAPI terms, **paths** are endpoints (resources), such as `/users` or `/reports/summary/`, that your API exposes, and **operations** are the HTTP methods used to manipulate these paths, such as GET, POST or DELETE.

### Paths

API paths and operations are defined in the global `paths` section of the API specification.

{% code lineNumbers="true" %}

```yaml
paths:
  /ping:
    ...
  /users:
    ...
  /users/{id}:
    ...
```

{% endcode %}

All paths are relative to the [API server URL](/docs/open-api-guide/api-server-and-base-path.md). The full request URL is constructed as `<server-url>/path`. Global `servers` can also be overridden on the path level or operation level (more on that [below](#overriding-global-servers)). Paths may have an optional short `summary` and a longer `description` for documentation purposes. This information is supposed to be relevant to all operations in this path. `description` can be [multi-line](http://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines) and supports [Markdown](http://commonmark.org/help/) (CommonMark) for rich text representation.

{% code lineNumbers="true" %}

```yaml
paths:
  /users/{id}:
    summary: Represents a user
    description: >
      This resource represents an individual user in the system.
      Each user is identified by a numeric `id`.
    get:
      ...
    patch:
      ...
    delete:
      ...
```

{% endcode %}

### Path Templating

You can use curly braces `{}` to mark parts of an URL as [path parameters](/docs/open-api-guide/describing-parameters.md#path-parameters):

{% code lineNumbers="true" %}

```yaml
/users/{id}
/organizations/{orgId}/members/{memberId}
/report.{format}
```

{% endcode %}

The API client needs to provide appropriate parameter values when making an API call, such as `/users/5` or `/users/12`.

### Operations

For each path, you define operations (HTTP methods) that can be used to access that path. OpenAPI 3.0 supports `get`, `post`, `put`, `patch`, `delete`, `head`, `options`, and `trace`. A single path can support multiple operations, for example `GET /users` to get a list of users and `POST /users` to add a new user. OpenAPI defines a unique operation as a combination of a path and an HTTP method. This means that two GET or two POST methods for the same path are not allowed – even if they have different parameters (parameters have no effect on uniqueness). Below is a minimal example of an operation:

{% code lineNumbers="true" %}

```yaml
paths:
  /ping:
    get:
      responses:
        '200':
          description: OK
```

{% endcode %}

Here is a more detailed example with parameters and response schema:

{% code lineNumbers="true" %}

```yaml
paths:
  /users/{id}:
    get:
      tags:
        - Users
      summary: Gets a user by ID.
      description: >
        A detailed description of the operation.
        Use markdown for rich text representation,
        such as **bold**, *italic*, and [links](https://swagger.io).
      operationId: getUserById
      parameters:
        - name: id
          in: path
          description: User ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      externalDocs:
        description: Learn more about user operations provided by this API.
        url: http://api.example.com/docs/user-operations/
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
      required:
        - id
        - name
```

{% endcode %}

Operations also support some optional elements for documentation purposes:

* A short `summary` and a longer `description` of what an operation does. `description` can be [multi-line](http://stackoverflow.com/questions/3790454/in-yaml-how-do-i-break-a-string-over-multiple-lines) and supports [Markdown](http://commonmark.org/help/) (CommonMark) for rich text representation.
* `tags` – used to group operations logically by resources or any other qualifier. See [Grouping Operations With Tags](/docs/open-api-guide/grouping-operations-with-tags.md).
* `externalDocs` – used to reference an external resource that contains additional documentation.

### Operation Parameters

OpenAPI 3.0 supports operation parameters passed via path, query string, headers, and cookies. You can also define the request body for operations that transmit data to the server, such as POST, PUT and PATCH. For details, see [Describing Parameters](/docs/open-api-guide/describing-parameters.md) and [Describing Request Body](/docs/open-api-guide/describing-request-body.md).

### Query String in Paths

Query string parameters **must not** be included in paths. They should be defined as [query parameters](/docs/open-api-guide/describing-parameters.md#query-parameters) instead.

Incorrect:

{% code lineNumbers="true" %}

```yaml
paths:
  /users?role={role}:
```

{% endcode %}

Correct:

{% code lineNumbers="true" %}

```yaml
paths:
  /users:
    get:
      parameters:
        - in: query
          name: role
          schema:
            type: string
            enum: [user, poweruser, admin]
          required: true
```

{% endcode %}

This also means that it is impossible to have multiple paths that differ only in query string, such as:

{% code lineNumbers="true" %}

```yaml
GET /users/findByName?firstName=value&lastName=value
GET /users/findByRole?role=value
```

{% endcode %}

### operationId

`operationId` is an optional unique string used to identify an operation. If provided, these IDs must be unique among all operations described in your API.

{% code lineNumbers="true" %}

```yaml
/users:
  get:
    operationId: getUsers
    summary: Gets all users
    ...
  post:
    operationId: addUser
    summary: Adds a new user
    ...
/user/{id}:
  get:
    operationId: getUserById
    summary: Gets a user by user ID
    ...
```

{% endcode %}

Some common use cases for operationId are:

* Some code generators use this value to name the corresponding methods in code.
* [Links](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#linkObject) can refer to the linked operations by `operationId`.

### Deprecated Operations

You can mark specific operations as `deprecated` to indicate that they should be transitioned out of usage:

{% code lineNumbers="true" %}

```yaml
/api/v1/product:
  post:
    deprecated: true
```

{% endcode %}

Tools may handle deprecated operations in a specific way. For example, Swagger UI displays them with a different style:

<figure><img src="/files/Btpmxk8dqV2e2WU5oOH3" alt=""><figcaption></figcaption></figure>

### Overriding Global Servers

The global `servers` array can be overridden on the path level or operation level. This is useful if some endpoints use a different server or base path than the rest of the API. Common examples are:

* Different base URL for file upload and download operations.
* Deprecated but still functional endpoints.

{% code lineNumbers="true" %}

```yaml
servers:
  - url: https://api.example.com/v1
paths:
  /files:
    description: File upload and download operations
    servers:
      - url: https://files.example.com
        description: Override base path for all operations with the /files path
    ...
  /ping:
    get:
      servers:
        - url: https://echo.example.com
          description: Override base path for the GET /ping operation
```

{% endcode %}