Developer Guide

API Mock Stubbing Guide

This guide explains how to use mock stubs when calling APIs to simulate different responses without hitting real backend services.

Mock stubbing is available in non-production environments only (dev, agile, staging).

Quick Start

Enable mock responses by adding these headers to your API request:

X-Mock-Response: true
X-Mock-Path: /orders
X-Mock-Scenario: success

Required Headers

X-Mock-Response

• Required: Yes (to enable mocking)
• Value: true
• Description: Activates the mock stubbing middleware

X-Mock-Path

• Required: Yes
• Value: The API path pattern (e.g., /orders, /orders/{id}, /users/{id}/profile)
• Description: Specifies which stub file to use. Use {id} as a placeholder for dynamic path segments

X-Mock-Scenario

• Required: No
• Default: success
• Value: The scenario name (e.g., success, not-found, error, timeout)
• Description: Determines which stub variant to use for testing different cases

Path Patterns

Static Paths

For endpoints without dynamic parameters:

X-Mock-Path: /orders
X-Mock-Path: /users/settings

Dynamic Paths

Use {id} as a placeholder for IDs or dynamic segments:

X-Mock-Path: /orders/{id}
X-Mock-Path: /users/{id}/profile
X-Mock-Path: /companies/{id}/employees/{id}

Note: Leading and trailing slashes are optional - all these work the same:

• orders/{id}
• /orders/{id}
• /orders/{id}/

Common Scenarios

Success Response

curl -X GET https://api.example.com/orders/123 \
  -H "X-Mock-Response: true" \
  -H "X-Mock-Path: /orders/{id}" \
  -H "X-Mock-Scenario: success"

Not Found (404)

curl -X GET https://api.example.com/orders/999 \
  -H "X-Mock-Response: true" \
  -H "X-Mock-Path: /orders/{id}" \
  -H "X-Mock-Scenario: not-found"

Server Error (500)

curl -X POST https://api.example.com/orders \
  -H "X-Mock-Response: true" \
  -H "X-Mock-Path: /orders" \
  -H "X-Mock-Scenario: server-error" \
  -H "Content-Type: application/json" \
  -d '{"product": "widget"}'

Validation Error

curl -X POST https://api.example.com/orders \
  -H "X-Mock-Response: true" \
  -H "X-Mock-Path: /orders" \
  -H "X-Mock-Scenario: validation-error" \
  -H "Content-Type: application/json" \
  -d '{"product": ""}'

Dynamic Templating

Stub responses can include values pulled from your request using {{ ... }} syntax, so the response echoes back data you sent.

Available Template Variables

Complete Examples

Example 1: Get Order by ID

Request:

curl -X GET https://api.example.com/orders/12345 \
  -H "X-Mock-Response: true" \
  -H "X-Mock-Path: /orders/{id}" \
  -H "X-Mock-Scenario: success"

Response:

{
  "id": "12345",
  "status": "shipped",
  "items": [
    {
      "product": "Widget",
      "quantity": 2,
      "price": 29.99
    }
  ],
  "total": 59.98
}

Example 2: Create Order

Request:

curl -X POST https://api.example.com/orders \
  -H "X-Mock-Response: true" \
  -H "X-Mock-Path: /orders" \
  -H "X-Mock-Scenario: success" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Gadget",
    "quantity": 3,
    "userId": "user-456"
  }'

Response: (HTTP 201)

{
  "id": "new-order-789",
  "product": "Gadget",
  "quantity": "3",
  "userId": "user-456",
  "status": "pending",
  "createdAt": "2026-03-19T10:30:00Z"
}

Example 3: Not Found Error

Request:

curl -X GET https://api.example.com/orders/99999 \
  -H "X-Mock-Response: true" \
  -H "X-Mock-Path: /orders/{id}" \
  -H "X-Mock-Scenario: not-found"

Response: (HTTP 404)

{
  "error": "Order not found",
  "orderId": "99999",
  "message": "No order exists with ID 99999"
}

Testing Different Scenarios

Common scenarios you can test:

Error Responses

When Mock Headers Are Missing

Missing X-Mock-Path:

{
  "error": "X-Mock-Path header is required",
  "example": "X-Mock-Path: /orders"
}

Status: 400 Bad Request

When Stub Not Found

{
  "error": "Failed to fetch mock stub",
  "reason": "HTTP 404"
}

Status: 502 Bad Gateway

Tips & Best Practices

1. Use descriptive scenario names - Make it clear what behavior you're testing
2. Leverage {id} placeholders - Reuse stubs for any ID value
3. Test error cases - Don't just test happy paths
4. Consistent stub structure - Use the same patterns across your team
5. Document custom scenarios - Share available scenarios with your team

Troubleshooting

Q: Mock headers aren't working

• Ensure X-Mock-Response: true is set (case-sensitive headers)
• Verify X-Mock-Path is provided
• Check that mock stubbing is enabled for this API and environment

Q: Getting 404 errors

• Verify a stub exists for this path, method, and scenario
• Check with your API team whether the scenario name is correct

Q: Template variables showing as empty

• Ensure you're using the correct template syntax: {{request.path.id}}
• Check that path parameters match the pattern (e.g., {id} in path)
• Verify request body is valid JSON for body templates

Q: How do I find available scenarios?

• Check with your API team for the scenarios available for that endpoint
• Common scenarios are usually: success, not-found, error
• To request a new scenario, ask your API team to add it