Debugging

Request Inspector

One of api.vision's most powerful features is the built-in Request Inspector, which provides real-time visibility into all API requests and responses.

Using the Request Inspector

To access the Request Inspector:

1. Open your api.vision dashboard
2. Select the API you want to debug
3. Navigate to the "Inspector" tab

The inspector displays requests in real-time as they arrive. You can:

• Click on any request to view its details
• Filter requests by method, path, or status code
• Search for specific content in requests or responses
• Clear the log to start fresh

Debug Mode

Enable debug mode for additional information in your API responses:

GET /users?_debug=true

When debug mode is enabled, responses include additional metadata:

{
  "data": [...],
  "_debug": {
    "query": {
      "filters": { "role": "admin" },
      "sort": ["-createdAt"],
      "pagination": { "page": 1, "limit": 10 }
    },
    "timing": {
      "total": "125ms",
      "database": "87ms",
      "processing": "38ms"
    },
    "database": {
      "queryCount": 2,
      "queries": [
        { "sql": "SELECT * FROM users WHERE role = 'admin' ORDER BY created_at DESC LIMIT 10 OFFSET 0", "duration": "65ms" },
        { "sql": "SELECT COUNT(*) FROM users WHERE role = 'admin'", "duration": "22ms" }
      ]
    }
  }
}

Request Tracing

For complex operations, api.vision provides detailed request tracing:

GET /posts?expand=author,comments.author&_trace=true

This adds a trace of all processing steps in the response:

{
  "data": [...],
  "_trace": [
    { "stage": "init", "time": "2023-04-15T14:32:10.123Z", "duration": "2ms" },
    { "stage": "authentication", "time": "2023-04-15T14:32:10.125Z", "duration": "5ms" },
    { "stage": "authorization", "time": "2023-04-15T14:32:10.130Z", "duration": "3ms" },
    { "stage": "parse_query", "time": "2023-04-15T14:32:10.133Z", "duration": "4ms", "details": { ... } },
    { "stage": "fetch_posts", "time": "2023-04-15T14:32:10.137Z", "duration": "45ms", "details": { ... } },
    { "stage": "expand_author", "time": "2023-04-15T14:32:10.182Z", "duration": "28ms", "details": { ... } },
    { "stage": "expand_comments", "time": "2023-04-15T14:32:10.210Z", "duration": "38ms", "details": { ... } },
    { "stage": "expand_comments_author", "time": "2023-04-15T14:32:10.248Z", "duration": "35ms", "details": { ... } },
    { "stage": "finalize", "time": "2023-04-15T14:32:10.283Z", "duration": "3ms" }
  ]
}

Verbose Error Reporting

Enable verbose error reporting for detailed error information:

GET /users/999?_verbose=true

When verbose mode is enabled, error responses include additional details:

{
  "status": 404,
  "error": "Not Found",
  "message": "Resource with id '999' not found",
  "path": "/users/999",
  "_verbose": {
    "request": {
      "method": "GET",
      "path": "/users/999",
      "params": { "id": "999" },
      "query": { "_verbose": "true" }
    },
    "error": {
      "code": "RESOURCE_NOT_FOUND",
      "details": "No user exists with ID 999",
      "stack": "NotFoundError: Resource with id '999' not found\n    at ..."
    }
  }
}

Debugging Request Validation

When a request fails validation, api.vision provides detailed validation errors:

// Request
POST /users
{
  "username": "j",
  "role": "superadmin"
}

// Response
{
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "validationErrors": [
    {
      "field": "username",
      "error": "must be at least 3 characters long"
    },
    {
      "field": "email",
      "error": "is required"
    },
    {
      "field": "role",
      "error": "must be one of: user, admin, editor"
    }
  ]
}

Request and Response Logging

api.vision can automatically log all requests and responses to help with debugging:

• Console Logging: Logs to the console during development
• File Logging: Saves logs to files for later analysis
• External Logging: Integrates with services like Datadog, New Relic, or ELK Stack

Configure logging in your api.vision settings or in the API configuration:

{
  "logging": {
    "enabled": true,
    "level": "debug",
    "format": "json",
    "includeHeaders": true,
    "includeBodies": true,
    "excludePatterns": ["/health", "/metrics"],
    "excludeHeaders": ["authorization", "cookie"]
  }
}

Response Inspection

api.vision provides tools to understand how responses are generated:

GET /users?_inspect=data

This parameter reveals how the data was generated, including:

• The schema used to generate the data
• Any templates or faker functions that were applied
• Transformations or modifications made to the data

Network Simulation Debugging

When using network simulation features (latency, errors, etc.), you can inspect how they affect responses:

GET /users?_inspectNetwork=true

This reveals information about any artificial network conditions:

{
  "data": [...],
  "_network": {
    "latency": {
      "applied": true,
      "min": 100,
      "max": 300,
      "actual": 182
    },
    "errorRate": {
      "applied": true,
      "rate": 0.05,
      "triggered": false
    },
    "throttling": {
      "applied": true,
      "rate": 128000, // 128 kbps
      "originalSize": 24560,
      "additionalDelay": 192
    }
  }
}