Response Pipelines

Configure multi-stage response transformation pipelines that process mock responses before delivery. Pipelines enable header injection, pagination, compression, error injection, CORS handling, and custom transformations.

Prerequisites

• An existing mock simulation with responses
• Understanding of HTTP headers and response structure
• Familiarity with JSON payload structures

Understanding Response Pipelines

Response pipelines define ordered sequences of transformation stages applied to every response in a simulation.

Pipeline Flow:

Response Generated
    ↓
[Stage 1] Header Injection
    ↓
[Stage 2] Pagination
    ↓
[Stage 3] Envelope Wrapping
    ↓
[Stage 4] Field Filtering
    ↓
[Stage 5] Delay Simulation
    ↓
Response Delivered

Available Pipeline Stages

1. Header Injection

Inject custom headers into every response:

{
  "type": "header-injection",
  "name": "Add Security Headers",
  "enabled": true,
  "config": {
    "headers": {
      "X-Content-Type-Options": "nosniff",
      "X-Frame-Options": "DENY",
      "X-XSS-Protection": "1; mode=block",
      "Strict-Transport-Security": "max-age=31536000"
    },
    "overwrite": false
  }
}

Config:

• headers - Headers to inject (key-value pairs)
• overwrite - Replace existing header if present (default: false)

2. Pagination

Wrap array responses in pagination envelope:

{
  "type": "pagination",
  "name": "Wrap in Pagination",
  "enabled": true,
  "config": {
    "enabled": true,
    "pathToArray": "items",
    "pageSize": 20,
    "pageParam": "page",
    "limitParam": "limit",
    "pageFormat": "1-based"
  }
}

Config:

• pathToArray - JSON path to array in response (e.g., "items", "data.users")
• pageSize - Default items per page
• pageParam - Query param for page number
• limitParam - Query param for page size
• pageFormat - "0-based" or "1-based" page numbering

3. Envelope

Wrap response body in envelope structure:

{
  "type": "envelope",
  "name": "API Envelope",
  "enabled": true,
  "config": {
    "wrapper": "data",
    "includeMetadata": true,
    "metadata": {
      "version": "v1",
      "environment": "mock"
    }
  }
}

Config:

• wrapper - Property to wrap body under (e.g., "data", "result")
• includeMetadata - Add metadata wrapper (boolean)
• metadata - Static metadata fields to include

Example output:

{
  "data": { "id": "123", "name": "John" },
  "metadata": {
    "version": "v1",
    "environment": "mock",
    "timestamp": "2026-01-15T10:00:00Z"
  }
}

4. Field Filter

Remove sensitive or unwanted fields:

{
  "type": "field-filter",
  "name": "Remove Sensitive Fields",
  "enabled": true,
  "config": {
    "mode": "exclude",
    "fields": ["password", "internalId", "debugInfo"],
    "recursive": true
  }
}

Config:

• mode - "include" (keep only these) or "exclude" (remove these)
• fields - Field names to include/exclude
• recursive - Apply to nested objects (boolean)

5. Delay by Size

Add latency based on response size:

{
  "type": "delay-by-size",
  "name": "Size-Based Latency",
  "enabled": true,
  "config": {
    "baseLatencyMs": 50,
    "bytesPerMs": 0.1,
    "maxLatencyMs": 2000
  }
}

Config:

• baseLatencyMs - Minimum latency
• bytesPerMs - Milliseconds to add per byte
• maxLatencyMs - Cap on total latency

Example: 1KB response = 50 + (1000 * 0.1) = 150ms

6. Compression

Compress response body:

{
  "type": "compression",
  "name": "GZIP Compression",
  "enabled": true,
  "config": {
    "algorithm": "gzip",
    "minSizeBytes": 1024
  }
}

Config:

• algorithm - "gzip" or "deflate"
• minSizeBytes - Only compress if larger than this

7. Error Rate

Inject errors at specified rate:

{
  "type": "error-rate",
  "name": "5% Error Injection",
  "enabled": true,
  "config": {
    "errorRate": 0.05,
    "statusCode": 500,
    "body": {
      "error": "Internal server error",
      "message": "Simulated error"
    }
  }
}

Config:

• errorRate - Probability 0-1 (0.05 = 5%)
• statusCode - HTTP status for errors
• body - Error response body

8. Transform

Custom transformation with template syntax:

{
  "type": "transform",
  "name": "Add Timestamps",
  "enabled": true,
  "config": {
    "transformations": [
      {
        "path": "createdAt",
        "value": "{{now:iso}}"
      },
      {
        "path": "requestId",
        "value": "{{request.headers.x-request-id}}"
      }
    ]
  }
}

Template Variables:

• {{now:iso}} - Current ISO timestamp
• {{request.method}} - HTTP method
• {{request.path}} - Request path
• {{request.headers.x-custom}} - Request header
• {{random:uuid}} - Random UUID
• {{random:int:1:100}} - Random integer

9. CORS

Configure CORS headers:

{
  "type": "cors",
  "name": "CORS Headers",
  "enabled": true,
  "config": {
    "allowedOrigins": ["https://localhost:3000", "https://app.example.com"],
    "allowedMethods": ["GET", "POST", "PUT", "DELETE"],
    "allowedHeaders": ["Content-Type", "Authorization"],
    "exposedHeaders": ["X-Total-Count"],
    "credentials": true,
    "maxAge": 3600
  }
}

Config:

• allowedOrigins - Origins allowed to access
• allowedMethods - HTTP methods allowed
• allowedHeaders - Headers request can send
• exposedHeaders - Headers response can expose
• credentials - Allow credentials (boolean)
• maxAge - Cache duration in seconds

10. Cache Control

Set HTTP caching headers:

{
  "type": "cache-control",
  "name": "Browser Caching",
  "enabled": true,
  "config": {
    "directive": "public",
    "maxAge": 3600,
    "sMaxAge": 86400,
    "revalidate": true,
    "etag": true
  }
}

Config:

• directive - "public" or "private"
• maxAge - Browser cache duration (seconds)
• sMaxAge - Shared cache duration (seconds)
• revalidate - Add must-revalidate directive
• etag - Generate ETag header

Creating a Pipeline

Access Pipeline Configuration

1. Open mock simulation
2. Click Settings or gear icon
3. Select Pipeline tab
4. Click Create Pipeline or Add Stage

Add Stage

1. Click Add Stage
2. Select stage type from dropdown
3. Configure stage:

{
  "type": "header-injection",
  "name": "Security Headers",
  "enabled": true,
  "config": { ... }
}

4. Click Save
5. Stage is added to pipeline

Reorder Stages

Stages execute top-to-bottom. Reorder to change execution sequence:

1. Click Reorder or drag handle
2. Drag stages to new positions
3. Click Save Order

Important: Order matters!

• Headers should go before compression
• Transformation before filtering
• Error injection after envelope

Update Stage

Edit a stage configuration:

1. Click stage
2. Click Edit
3. Update configuration
4. Click Save

Changes take effect immediately.

Remove Stage

Delete a stage from pipeline:

1. Click stage
2. Click Delete or Remove
3. Confirm deletion
4. Stage is removed from pipeline

Enable/Disable Stage

Temporarily disable without removing:

1. Click stage
2. Toggle Enabled switch
3. Stage is skipped but not deleted

Useful for testing with/without stages.

Previewing Pipeline Output

Test pipeline before deploying:

Preview with Sample Data

1. Click Preview button
2. Enter sample response data:

{
  "statusCode": 200,
  "body": {
    "items": [
      { "id": "1", "name": "Item 1", "password": "secret" },
      { "id": "2", "name": "Item 2", "password": "secret" }
    ]
  },
  "headers": {
    "Content-Type": "application/json"
  }
}

3. Click Run Preview
4. See transformed output:

{
  "statusCode": 200,
  "headers": {
    "Content-Type": "application/json",
    "X-Content-Type-Options": "nosniff",
    "Cache-Control": "public, max-age=3600"
  },
  "body": {
    "data": {
      "items": [
        { "id": "1", "name": "Item 1" },
        { "id": "2", "name": "Item 2" }
      ],
      "pagination": {
        "page": 1,
        "pageSize": 20,
        "total": 2
      }
    },
    "metadata": { "version": "v1" }
  }
}

Test with Actual Request

1. Make request to simulation
2. Compare response against expected
3. Adjust pipeline stages as needed
4. Re-test

Common Pipeline Configurations

REST API Standard

Envelope + pagination + headers + caching:

[
  {
    "type": "envelope",
    "config": { "wrapper": "data" }
  },
  {
    "type": "pagination",
    "config": {
      "pathToArray": "data",
      "pageSize": 20
    }
  },
  {
    "type": "header-injection",
    "config": {
      "headers": {
        "X-API-Version": "1.0",
        "X-Powered-By": "SureStage"
      }
    }
  },
  {
    "type": "cache-control",
    "config": { "maxAge": 3600 }
  }
]

Security Hardened

Security headers + compression + field filtering:

[
  {
    "type": "field-filter",
    "config": {
      "mode": "exclude",
      "fields": ["internalId", "debugInfo", "apiKey"]
    }
  },
  {
    "type": "header-injection",
    "config": {
      "headers": {
        "X-Content-Type-Options": "nosniff",
        "X-Frame-Options": "DENY",
        "X-XSS-Protection": "1; mode=block"
      }
    }
  },
  {
    "type": "compression",
    "config": { "algorithm": "gzip" }
  }
]

Error Simulation

Headers + error injection + delays:

[
  {
    "type": "delay-by-size",
    "config": { "baseLatencyMs": 100 }
  },
  {
    "type": "error-rate",
    "config": {
      "errorRate": 0.1,
      "statusCode": 503
    }
  },
  {
    "type": "header-injection",
    "config": {
      "headers": { "Retry-After": "60" }
    }
  }
]

Pipeline Best Practices

Order of Stages

Recommended order:

1. Transform - Modify data first
2. Field Filter - Remove unwanted fields
3. Envelope - Wrap in structure
4. Pagination - Add pagination
5. Error Rate - Inject errors if needed
6. Delay - Add latency
7. Compression - Compress payload
8. Headers - Add HTTP headers
9. CORS - Add CORS headers
10. Cache - Set caching headers

Performance Considerations

• Enable compression for large payloads
• Disable stages not in use
• Place expensive operations late (error rate after envelope)
• Use delay-by-size sparingly
• Test with realistic data

Testing Pipelines

1. Start with simple stages
2. Test each stage individually
3. Test interaction with other stages
4. Use preview feature before deploying
5. Monitor actual traffic for issues

Troubleshooting

Pipeline Not Applying

• Verify pipeline is enabled for simulation
• Check stage is marked as enabled
• Confirm correct stage type selected
• Test with preview feature

Response Malformed

• Check envelope wrapper doesn't conflict with existing data
• Verify field filter doesn't remove required fields
• Ensure transformation syntax is correct
• Use preview to see intermediate output

Performance Issues

• Check if compression is enabled (large payloads)
• Disable delay-by-size if not needed
• Reduce error-rate injection
• Review stage count (too many = overhead)

Headers Not Appearing

• Verify header-injection stage enabled
• Check stage is after other modifications
• Use preview to see actual headers
• Confirm header names are correct

API Reference

Pipeline Management

Method	Path	Description
GET	/instances/:id/pipeline	Get pipeline
PUT	/instances/:id/pipeline	Replace pipeline
POST	/instances/:id/pipeline/stages	Add stage
PATCH	/instances/:id/pipeline/stages/:stageId	Update stage
DELETE	/instances/:id/pipeline/stages/:stageId	Remove stage
POST	/instances/:id/pipeline/reorder	Reorder stages
POST	/instances/:id/pipeline/preview	Preview output

Next Steps

• Routes and Responses - Create responses to pipeline
• Response Versioning - Track pipeline changes
• Analytics - Monitor transformation metrics
• Performance Tuning - Optimize latency