Folder

Folders help you organize endpoints within a Collection into logical groups. Create nested hierarchies to mirror your API structure and keep related endpoints together.

What is a Folder?

A Folder is an organizational container within a Collection that groups related endpoints. Folders can be nested to create hierarchical structures that match your API's logical organization.

Use Folders to organize by:

• Resource type (e.g., "Users", "Orders", "Products")
• API version (e.g., "v1", "v2", "beta")
• Feature area (e.g., "Authentication", "Payment", "Reporting")
• Environment (e.g., "Development", "Staging", "Production")
• HTTP methods (e.g., "GET", "POST", "Admin")

Folder Hierarchy

Folders can be nested to create multi-level hierarchies, helping you organize complex APIs with many endpoints.

Example Structure

📁 Collection: User Service

📁 Folder: Authentication

📄 POST /login

📄 POST /logout

📄 POST /refresh-token

📁 Folder: Users

📁 Folder: Public

📄 GET /users

📄 GET /users/:id

📁 Folder: Admin

📄 POST /users

📄 PUT /users/:id

📄 DELETE /users/:id

📁 Folder: Profile

📄 GET /profile

📄 PUT /profile

📄 POST /profile/avatar

Benefits of Using Folders

Better Organization

Group related endpoints together instead of having a flat list. Find what you need quickly with logical categorization.

Clear Structure

Mirror your actual API architecture in your mock setup. This makes it easier to understand and maintain as your API grows.

Team Collaboration

Organize endpoints by team ownership or feature areas. Multiple team members can work on different folders without conflicts.

Easier Navigation

Collapse and expand folders to focus on relevant sections. Reduce clutter and improve workspace clarity.

Path Configuration

Folders can define a path pattern that applies to all Responses within that Folder. Paths can be either static routes or regular expressions for flexible matching.

Static Paths

Use static paths for exact route matching. Paths must start with a forward slash /.

Examplestext

/users
/api/v1/products
/admin/settings
/orders/123

Regular Expression Paths

Use regular expression paths for dynamic route matching. Regex paths must start with regex:/ and can capture groups for use in response templates.

Examplestext

regex:/users/(\d+)
regex:/api/v(\d+)/products/([a-z]+)
regex:/orders/(\d+)/items/(\d+)
regex:/posts/(\d+)/comments/(\d+)

💡 Capturing Groups

Use parentheses () to create capture groups. Captured values can be accessed in response templates using {{path.regex $1}}, {{path.regex $2}}, etc.

Learn more about using path values in templates in Template Syntax Reference.

⚠️ Path Format Rules

• Static paths must start with /
• Regex paths must start with regex:/
• Path segments are indexed starting from 1 (not 0)
• Regex capture groups are indexed starting from 1
• Use parentheses () to create capture groups in regex

Configuration Inheritance

Settings configured at the Folder level automatically apply to all Responses within that Folder. This allows you to define common configurations once and have them inherited by all endpoints.

💡 Inheritance Rule

All Responses within a Folder automatically inherit the Folder's settings. If a Response defines the same setting, the Response-level setting takes priority.

Settings That Inherit

• Headers: Response headers like Content-Type, CORS, authentication tokens, and custom headers
• Rules: Conditional logic that determines which responses to return based on request data
Future: Authentication settings and other configurations will also support inheritance

Inheritance Example

📁 Folder: API v2

Headers: Content-Type: application/json

Rules: API Key validation required

📄 Response: GET /users

→ Headers: (inherited) Content-Type: application/json

→ Rules: (inherited) API Key validation

📄 Response: GET /export

Headers: Content-Type: text/csv (override!)

→ Headers: Content-Type: text/csv (Response priority)

→ Rules: (inherited) API Key validation

Priority Rules

1. Response-level settings have highest priority

When a Response defines its own Headers or Rules, they completely override the Folder settings (no merging)

2. Folder-level settings are inherited by default

If a Response doesn't define Headers or Rules, it automatically uses the Folder's configuration

3. More specific always wins

The principle: specific Response settings > general Folder settings

Practical Use Cases

• Common CORS Headers

Set CORS headers at the Folder level to apply them to all endpoints in that folder, eliminating repetition

• Authentication Requirements

Group authenticated endpoints in a folder with shared authentication Rules, ensuring consistent security

• API Version Headers

Add version headers at the API version folder level (e.g., "v2") to automatically include them in all responses

• Content-Type Defaults

Set default Content-Type in folder, override only for special cases like CSV exports or HTML responses

💡 Tip: Use Folder-level settings to reduce duplication and improve maintainability. When you update a Folder's Headers or Rules, all child Responses automatically receive the changes (unless they override).

Learn more about Response configuration in Response Overview

Real-World Examples

1. E-commerce API

Organize by resource type and access level

text

📁 Collection: E-commerce API
  📁 Products
    📄 GET /products
    📄 GET /products/:id
    📁 Admin
      📄 POST /products
      📄 PUT /products/:id
      📄 DELETE /products/:id
  📁 Orders
    📄 GET /orders
    📄 POST /orders
    📄 GET /orders/:id
  📁 Cart
    📄 GET /cart
    📄 POST /cart/items
    📄 DELETE /cart/items/:id
  📁 Checkout
    📄 POST /checkout
    📄 GET /checkout/payment-methods

2. Multi-Version API

Organize by API version for gradual migration

text

📁 Collection: Payment Service
  📁 v1 (Legacy)
    📄 POST /v1/payments
    📄 GET /v1/payments/:id
  📁 v2 (Current)
    📄 POST /v2/payments
    📄 GET /v2/payments/:id
    📄 POST /v2/payments/:id/refund
    📄 GET /v2/payment-methods
  📁 v3 (Beta)
    📄 POST /v3/payments
    📄 GET /v3/payments/:id
    📄 POST /v3/payments/batch

3. Microservices Structure

Organize by microservice domain

text

📁 Collection: Platform API
  📁 User Service
    📁 Authentication
      📄 POST /auth/login
      📄 POST /auth/register
    📁 Profile
      📄 GET /users/me
      📄 PUT /users/me
  📁 Notification Service
    📁 Email
      📄 POST /notifications/email
    📁 Push
      📄 POST /notifications/push
  📁 Analytics Service
    📁 Events
      📄 POST /analytics/events
    📁 Reports
      📄 GET /analytics/reports/:type

4. Feature-Based Organization

Organize by feature or workflow

text

📁 Collection: SaaS Application
  📁 Onboarding
    📄 POST /signup
    📄 POST /verify-email
    📄 POST /setup-organization
  📁 Subscription
    📄 GET /plans
    📄 POST /subscribe
    📄 PUT /subscription/upgrade
    📄 DELETE /subscription/cancel
  📁 Billing
    📄 GET /invoices
    📄 GET /payment-methods
    📄 POST /payment-methods
  📁 Team Management
    📄 GET /team/members
    📄 POST /team/invite
    📄 DELETE /team/members/:id

Best Practices

📁 Keep It Shallow

Avoid deeply nested folder structures (more than 3-4 levels). Too many levels make navigation difficult and can indicate over-organization.

✅ Use Clear Names

Name folders clearly and consistently. Use plural nouns for resource folders (e.g., "Users", "Orders") and descriptive names for functional groupings (e.g., "Authentication", "Admin").

⚡ Group by Similarity

Group endpoints that share common concerns together. This could be by resource, feature, access level, or any logical grouping that makes sense for your API.

🎯 Match Real Structure

Mirror your actual API or application structure when possible. This makes the mock setup intuitive and helps developers understand the real system.

🔄 Refactor When Needed

Don't be afraid to reorganize folders as your API evolves. Good organization adapts to changing requirements and team needs.

When NOT to Use Folders

Folders are optional. You don't need folders if:

• Your Collection has fewer than 10 endpoints
• All endpoints are closely related and don't need subcategories
• You're prototyping and need quick setup without organization overhead
• Your API structure is completely flat with no logical groupings

Start simple and add folders as your Collection grows and organization becomes valuable.

Next Steps

Learn how to configure endpoints within your folders:

→ Response Overview - Learn about Response configuration
→ Templates - Generate dynamic response bodies
→ Rules - Add conditional response logic