Response Mocking

The mocking system allows you to simulate API responses for specific endpoints during development and testing. Mock responses can be filtered by path, HTTP method, query parameters, and headers using the gorilla/mux route matching system.

Key features:

• Path-based matching - define which URLs to intercept
• Method-specific - target specific HTTP methods (GET, POST, etc.)
• Query parameter filtering - match requests with specific query strings
• Header matching - filter by HTTP headers
• Configurable responses - control status codes, headers, delays, and content

Configuration structure:

mappings:
  - from: ...
    to: ...
    mocks:
      - path: /example-endpoint
        method: POST
        queries:
          param1: value1
          param2: value2
        headers:
          Content-Type: application/json
        response:
          code: 201
          headers:
            Content-Type: application/json
          delay: 10s
          raw: '{ "ok": true }'

Request Matching

Configure which requests should be intercepted by the mock.

Path (Required)

Defines the URL path to mock. Supports static paths and variable segments.

Examples:

path: /api/users              # Static path
path: /users/{id}             # Variable segment
path: /posts/{postId}/comments/{commentId}  # Multiple variables

Variable segments (e.g., {id}) match any value in that position. A request to /users/123 matches /users/{id}.

Method (Optional)

Specifies the HTTP method to match.

Property	Type	Default	Description
method	string	Any	HTTP method: GET, POST, PUT, DELETE, PATCH, etc.

If omitted, the mock matches all HTTP methods.

Query Parameters (Optional)

Match requests with specific query string parameters.

queries:
  param1: value1
  param2: value2

If omitted, all query parameter combinations are matched.

Headers (Optional)

Match requests with specific HTTP headers.

headers:
  Content-Type: application/json
  Authorization: Bearer token123

If omitted, all header combinations are matched.

Response Configuration

Define the response returned when a mock is triggered.

Response Properties

Property	Type	Required	Default	Description
code	integer	No	200	HTTP status code (e.g., 200, 404, 500)
headers	object	No	-	Custom HTTP headers to include in response
delay	string	No	-	Response delay (e.g., 1m 30s, 500ms)
raw	string	Conditional*	-	Raw response content
file	string	Conditional*	-	Path to file containing response content

*One of raw or file must be specified.

Status Code

response:
  code: 201

Headers

Add or override response headers:

response:
  headers:
    Content-Type: application/json
    X-Custom-Header: value

Delay

Simulate network latency or slow endpoints. Format: <number><unit> [<number><unit> ...]

Supported units:

Unit	Meaning
ns	Nanoseconds
us/µs	Microseconds
ms	Milliseconds
s	Seconds
m	Minutes
h	Hours

Examples:

delay: 500ms          # Half a second
delay: 1m 30s         # 1 minute 30 seconds
delay: 2s 500ms       # 2.5 seconds

Response Content

Choose one of two methods to provide response content:

Raw content - inline text or JSON:

response:
  raw: '{"message": "Success", "id": 123}'

File content - load response from a file:

response:
  file: ~/mocks/users-response.json

Dynamic Responses

For dynamic responses including request-dependent data, use the Script Handler (see Script Handler documentation for details).