Rewrite & Scripts

Rewrite rules mock, redirect, delay, or modify APIs on device. When a rule cannot cover dynamic work, use a JavaScript script to intercept the request.

How to write scripts: Script Guide.

Table of Contents

1. Scope
2. Rewrite rules
3. JavaScript scripts

1. Scope

Scope is where a rule or script applies: Host + Path. Host is required; Path is optional.

• Host: the rule or script runs on every request to that host. Matching is fuzzy — enter the apex domain (example.com) and subdomains match too. Pick a captured host from the dropdown, or type one.
• Path (optional): with a path set, only that API is targeted. Path is prefix-only (do not write * wildcards). /api/v1 matches /api/v1/users and /api/v1/orders. After you pick a Host, choose an API from the list (Method and Path fill in) or type a path.

Tip: Choosing an existing API fills Method and Path. On a rewrite rule it also prefills Mock templates or Headers.

2. Rewrite rules

While frontend and backend move in parallel, the API may not exist yet, or you need error status codes. Rewrite rules cover Mock and boundary tests. Where a rule applies: 1. Scope.

2.1 Rewrite Action

• Redirect: send the request somewhere else (production → localhost or staging).
• Mock: skip the network and return your JSON/XML, status (404, 500, …), headers, and body.
• Drop:
  • Drop Request: as if the request never left (offline).
  • Drop Response: the request is sent, no response comes back (timeout).
• Delay: add latency to test loading on a slow network.
• Modify:
  • Headers: inject a test token, or change User-Agent.
  • Replace Body: replace the whole request or response body.
  • Regex find-and-replace Body: patch JSON fields. For example, "status": "pending" → "status": "success".

Troubleshooting

• Rule does nothing: a newer, higher-priority rule is winning.
• Regex miss: JSON often has spaces and indentation. If the pattern does not allow whitespace (\s*), it can fail. Use the built-in Test panel.

3. JavaScript scripts

For Mock that needs computation (timestamp signatures, assembled payloads), scripts are the programmable path. They use the same scope: 1. Scope.

3.1 Tools

Besides writing code by hand, ApiCatcher helps you author and verify scripts:

• AI generate: describe the change in plain language (e.g. “set price to 9.9 and add discount_tag: true”) and the assistant fills in JS.
• Test Script: run against a captured request before you save. You get a before/after diff and errors. You can also console.log in the script and read the output on the Logs page.
• Remote Script: paste a public http:// or https:// URL. ApiCatcher loads and runs it locally — useful when a team shares one Mock.

3.2 Lifecycle functions

Details: Script Guide

Implement the hooks:

// Outgoing request
function interceptRequest(request) {
    // request.method, request.url, request.headers, request.body, request.queryParams
    if (request.path === '/api/v1/test') {
        request.headers['X-Debug-Token'] = 'test_token';
    }
    // Actions: passthrough, modify, mock, drop
    return { action: 'modify', request: request };
}

// Incoming response
function interceptResponse(request, response) {
    // response.statusCode, response.headers, response.body
    if (response.body) {
        var data = safeJsonParse(response.body); // built-in safe JSON parse
        if (data) {
            data.mock_field = true;
            response.body = JSON.stringify(data);
            return { action: 'modify', response: response };
        }
    }
    return { action: 'passthrough' };
}

3.3 Built-in APIs

• localStore: keep state across requests. Save auth on login, inject it on later APIs.
  • localStore.write('session_id', 'abc')
  • var t = localStore.read('session_id')
• httpClient: extra HTTP calls while the script runs (sync external state, fetch config).
  • var res = httpClient.get('https://api.ipify.org')

Troubleshooting

• Syntax / runtime: use Test Script. console.log("...") shows on the Logs page.
• Lifecycle: if a higher-priority rewrite already Mocked or Dropped the request, the script does not run for that request.