The Paths Object — Defining Endpoints and Operations

In this tutorial, you will learn about The Paths Object. We cover key concepts, practical examples, and best practices to help you master this topic.

The paths object in OpenAPI contains all API endpoint definitions, mapping relative URLs to operation objects that specify HTTP methods, parameters, request bodies, and responses.

In this tutorial, you will learn how to structure the paths object, define operations for each HTTP method, use operation IDs, and organize endpoints with tags.

What You'll Learn

You will learn how to define API endpoints in the paths object, configure operations for GET, POST, PUT, PATCH, and DELETE, use tags for grouping, and set operation metadata.

Why It Matters

The paths object is the core of any OpenAPI spec. It defines what the API can do. Every tool reads paths to generate documentation, build SDKs, and validate requests.

Real-World Use

DodaTech organizes paths by resource domain. Each resource has a set of paths for CRUD operations, grouped by tags. Common patterns like pagination parameters are defined once and referenced across all paths.

flowchart LR
  A[Paths Object] --> B["/users"]
  A --> C["/users/{id}"]
  A --> D["/documents"]
  A --> E["/documents/{id}"]
  B --> F[GET]
  B --> G[POST]
  C --> H[GET]
  C --> I[PUT]
  C --> J[DELETE]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Path Structure

Each path starts with a forward slash and maps to operation objects:

paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      tags:
        - Users
      parameters: []
      responses: {}
    post:
      operationId: createUser
      summary: Create a new user
      tags:
        - Users
      requestBody: {}
      responses: {}
  /users/{userId}:
    get:
      operationId: getUser
      summary: Get a single user
      parameters: []
      responses: {}
    put:
      operationId: updateUser
      summary: Update a user
      parameters: []
      requestBody: {}
      responses: {}
    delete:
      operationId: deleteUser
      summary: Delete a user
      parameters: []
      responses: {}

Operation Object Fields

Each operation can have: tags for grouping, summary (brief description), description (detailed explanation), externalDocs for linking to external guides, operationId (unique identifier), parameters (input parameters), requestBody (for POST, PUT, PATCH), responses (required), deprecated (boolean flag), security (overrides global), and servers (overrides global).

/users:
    get:
      tags:
        - Users
      summary: List all users
      description: |
        Returns a paginated list of users.
        Use page and limit parameters for pagination.
      operationId: listUsers
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: Successful response

Operation IDs

Operation IDs are unique identifiers across the entire API. They are used by code generators to name functions.

# Consistent operation ID naming
paths:
  /users:
    get:
      operationId: listUsers
    post:
      operationId: createUser
  /users/{userId}:
    get:
      operationId: getUser
    put:
      operationId: updateUser
    patch:
      operationId: patchUser
    delete:
      operationId: deleteUser
  /users/{userId}/documents:
    get:
      operationId: listUserDocuments
    post:
      operationId: createUserDocument

Operation IDs should follow verbNoun naming: listUsers, createUser, getUser, updateUser, deleteUser.

Using Tags for Organization

Tags group related operations in documentation:

tags:
  - name: Users
    description: User account management
    externalDocs:
      description: User management guide
      url: https://docs.dodatech.com/users
  - name: Documents
    description: Document storage and retrieval
  - name: Authentication
    description: Login and token management

paths:
  /users:
    get:
      tags:
        - Users
  /users/{userId}:
    get:
      tags:
        - Users
  /auth/login:
    post:
      tags:
        - Authentication

Path Parameters

Path parameters use curly brace syntax and must be defined in the parameters section:

/users/{userId}/documents/{documentId}:
    get:
      summary: Get a user document
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: documentId
          in: path
          required: true
          schema:
            type: integer

Common Mistakes

1. Missing operationId — Not providing operation IDs. Code generators use operation IDs for function names. Without them, generated code has unhelpful names.

2. Inconsistent tag usage — Using tags inconsistently across operations. Each tag should group a coherent set of related operations.

3. Duplicate operation IDs — Using the same operationId for different operations. Operation IDs must be unique across the entire spec.

4. No summary field — Skipping the summary. The summary appears in documentation navigation and is the first thing developers see.

5. Incorrect path format — Paths must start with /. Using users instead of /users is a common error.

Practice Questions

1. What HTTP methods can you define for a path?
2. What is the purpose of an operationId?
3. How do tags help organize API documentation?
4. How are path parameters defined?
5. What fields are required in an operation?

Challenge

Design the paths object for a blog API with resources for posts, comments, authors, and categories. Define at least 15 operations across these resources, use consistent operation IDs, organize with tags, and include path parameters where needed.

FAQ

Mini Project

Create a complete paths specification for a task management API with resources for tasks, projects, and labels. Define CRUD operations for each resource, use consistent operation IDs, organize with tags, and include path parameters for resource identification.

What's Next

In the next lesson, you will learn how to define operations for each HTTP method with detailed parameter and response documentation.