Defining Paths in OpenAPI: Mapping Your REST API Endpoints

Previously in this course, we explored the Introduction to OpenAPI Specification: Standardizing Your API. While that lesson explained why we use OpenAPI to standardize documentation, this lesson focuses on the how: mapping your existing Task Manager API endpoints into the paths section of an OpenAPI definition file.

Understanding the OpenAPI paths Object

In the OpenAPI Specification, the paths object is the heart of your documentation. It serves as a directory for every URL your API exposes. Each path is defined relative to the API's base URL and must start with a forward slash (/).

Under each path, you define the HTTP methods (GET, POST, PUT, DELETE) that the path supports. This structure tells developers exactly which operations they can perform on a specific resource.

Mapping the Task Manager Endpoints

Let’s translate our existing /v1/tasks collection into an OpenAPI definition. In our project, we have a base path for tasks and a path for individual tasks identified by an ID.

Here is how you structure that in a openapi.yaml file:

YAML
openapi: 3.0.0
info:
  title: Task Manager API
  version: 1.0.0

paths:
  /v1/tasks:
    get:
      summary: Retrieve all tasks
      description: Returns a list of tasks from the system.
    post:
      summary: Create a new task
      description: Adds a new task to the task collection.
  
  /v1/tasks/{taskId}:
    get:
      summary: Get task by ID
      description: Returns a single task object based on its ID.

Key Principles of Path Definition

1. Use Curly Braces for Parameters: When a path contains a variable (like a task ID), use curly braces {} to denote the path parameter. This signals to tools like Swagger UI that this part of the URL is dynamic.
2. Method-First Hierarchy: Always nest your HTTP methods directly under the path string. OpenAPI is case-sensitive, so ensure your methods are always lowercase (get, post, etc.).
3. Indentation Matters: Since you are writing in YAML, indentation is functional. Each method must be indented two spaces relative to its parent path.

Hands-on Exercise

Open your project's openapi.yaml file. Add the following paths to your definition to support our current Task Manager functionality:

1. Add the PUT /v1/tasks/{taskId} path to support full updates to a task.
2. Add the DELETE /v1/tasks/{taskId} path to allow for task removal.
3. Assign a summary to each of these new methods.

Once finished, verify your indentation. If you are using a tool like VS Code, the "OpenAPI (Swagger) Editor" extension can help you visualize if the structure is valid.

Common Pitfalls to Avoid

• Forgetting the Leading Slash: Paths must always start with /. Writing v1/tasks instead of /v1/tasks is a common mistake that will cause parsers to throw errors.
• Mixing JSON and YAML: While OpenAPI supports both, stick to one. YAML is generally preferred for its readability in documentation. If you find your file isn't validating, check for tabs—YAML strictly forbids them; use spaces only.
• Over-nesting: Keep your path definitions flat. Don't try to nest paths inside other paths; the paths object is a top-level property of the OpenAPI document.

Frequently Asked Questions

Does the order of paths in the file matter? No, the OpenAPI parser reads the entire structure. However, keeping them sorted alphabetically or by resource group makes the file much easier for humans to navigate.

Can I define the same path twice? No. If you have two different operations on the same path (like GET and POST), they must be grouped under the same path key.

How do I handle versioning in the path? As we discussed in API Versioning and Documentation: A Guide to System Stability, you should include the version explicitly in the path string (e.g., /v1/tasks), as shown in our example above.

Recap

We have successfully mapped our core Task Manager routes into an OpenAPI structure. By organizing our paths and methods, we have created a machine-readable map of our API. This foundational work allows us to move into adding more descriptive metadata, which will turn this skeleton into a professional-grade documentation set.

Up next: Adding Metadata to Documentation — we'll learn how to flesh out these paths with version info, contact details, and descriptive summaries.