OpenAPI Paths — Defining API Endpoints and Operations

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

OpenAPI paths are the core of the specification, defining each API endpoint with its HTTP methods, parameters, request bodies, expected responses, and security rules.

What You'll Learn

• Defining paths with multiple HTTP methods
• Path parameters and query parameters
• Request bodies and response definitions

Why It Matters

The paths section is where you describe your API surface. Well-defined paths make your spec clear and your documentation accurate.

Code Examples

paths:
  /users:
    get:
      summary: List all users
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            maximum: 100
          description: Maximum number of users
        - name: offset
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"

  /users/{userId}:
    get:
      summary: Get user by ID
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: User details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: User not found

    put:
      summary: Update user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserUpdate"
      responses:
        "200":
          description: User updated

# Parsing paths from OpenAPI
def list_all_endpoints(spec):
    endpoints = []
    for path, methods in spec.get('paths', {}).items():
        for method in methods:
            if method not in ('parameters',):
                endpoints.append({
                    'path': path,
                    'method': method.upper(),
                    'summary': methods[method].get('summary', '')
                })
    return endpoints

Common Mistakes

1. Not Using OperationId

operationId provides a unique identifier useful for Code Generation.

2. Missing Required Parameters

If a parameter is required, set required: true.

3. Forgetting 4xx and 5xx Responses

Document all possible error responses, not just 200.

4. Inconsistent Path Patterns

Use consistent patterns: /resource for collection, /resource/{id} for single.

5. No Request Body for POST/PUT

Specify the request body schema for operations that accept data.

Practice Questions

1. How do you define a path parameter in OpenAPI?
2. What is the purpose of operationId?
3. How do you define the request body for a POST endpoint?
4. What does the in: query parameter mean?
5. Should every response code be documented?

Answers:

1. Using {paramName} in the path and defining it in parameters with in: path.
2. It provides a unique name for the operation for code generation and documentation.
3. Under the requestBody field with content type and schema reference.
4. The parameter is a query parameter appended to the URL after ?.
5. Yes, to help clients handle all possible server responses correctly.

Challenge: Define paths for a blog API with endpoints for posts, comments, and authors. Include path parameters, query parameters, and request bodies.

FAQ

What's Next

Learn about OpenAPI Parameters in detail, then explore OpenAPI Request Body.