ApiCatcher User Manual

ApiCatcher is a professional-grade iOS network debugging tool built for developers, QA engineers, and network troubleshooters. By establishing a local virtual gateway, it helps you easily capture, view, analyze, and debug HTTP/HTTPS and WebSocket traffic for the applications you develop.

This manual will detail how to configure and use each feature module to assist in your daily development debugging, Mock testing, automated API analysis, and performance troubleshooting.

Basic Preparation: Certificate Configuration & Debug Authorization
Traffic Filtering: Precisely Target Debugging Goals
API Mocking & Modification: Rewrite Rules
Advanced Custom Processing: JavaScript Scripts
Automated Testing: Combo Replay
Background Monitoring: Scheduled Tasks
Quality & Performance Troubleshooting: API Scan
Utility Tools: Encryption/Decryption & Desktop Sync

1. Basic Preparation: Certificate Configuration & Debug Authorization

1.1 Install and Trust CA Certificate (Required for HTTPS Debugging)

Data interaction in modern applications is generally encrypted based on the HTTPS protocol. When developing and debugging your own applications, in order to properly view the plaintext request and response data of APIs, you need to configure and trust a debugging certificate to allow decryption.

ApiCatcher provides two ways to configure certificates:

Use the system's default generated CA certificate (Recommended for most scenarios): Follow the guide below to install the exclusive CA certificate automatically generated for you by ApiCatcher.
Import your own certificate (Enterprise Certificate): If you need to use an enterprise self-signed certificate, you can skip this section directly and read the 1.2 Enterprise Certificate Import section.

Steps to use the default CA certificate:

Click "Install Certificate" in the App, and the system will jump to the browser to download the configuration profile.
Go to iOS "Settings" -> "General" -> "VPN & Device Management", and install the downloaded ApiCatcher profile.
Crucial Step: Go to "Settings" -> "General" -> "About" -> "Certificate Trust Settings", find the certificate starting with ApiCatcher CA, and toggle the switch to enable full trust.

💡 Common Troubleshooting Guide:

Getting "Connection Timeout" or abnormal status codes during debugging: Usually because the certificate is not "fully trusted" in step 3.

Deleted the App and reinstalled: The old debugging certificate is now invalid. You must go to system settings to remove the old profile and repeat the above process again.

1.2 Enterprise Certificate Import (Enterprise Intranet Debugging Scenario)

During internal enterprise development and testing, some internal applications may configure specific certificate trust policies (e.g., only trusting the internal enterprise CA).

Usage: Import the .pem or .p12 certificate provided by the enterprise, and bind it with the internal test domain (e.g., *.corp.internal), to be used to complete legitimate TLS handshakes during local debugging.
Note: Import or modify configurations must be done while capture is stopped, and restarting is required for the changes to take effect.

1.3 Using Custom Certificates

For individual developers who do not have an enterprise certificate and do not want to use the default certificates provided by ApiCatcher, you can leverage the Enterprise Certificate feature to import your own custom certificates. For details, please refer to the documentation: Using Custom Certificates

2. Traffic Filtering: Precisely Target Debugging Goals

During the development process, to eliminate traffic interference from the underlying system and other background Apps, it is recommended to configure filtering rules to focus your attention on the project currently being debugged.

Blocklist: Domains appearing in the blocklist will not be recorded. If the allowlist is empty, all requests except those in the blocklist are recorded by default.
Allowlist: As long as there are rules in the allowlist, the system will only record requests matching the allowlist, and all other traffic will not enter the debugging channel.
Configuration Tips: Supports * wildcard. For example, entering *.example-api.com can match all test environment subdomains under that main domain.

💡 Common Troubleshooting Guide:

Cannot see the target application's requests: Please check if the allowlist is enabled but the target domain was missed, or if the target domain was mistakenly added to the blocklist.

Syntax Note: Please use basic asterisk matching (e.g., *.api.com); there is no need to write complex regular expressions.

3. API Mocking & Modification: Rewrite Rules (Rewrite)

During parallel development of front-end and back-end, back-end APIs are often not ready yet, or you need to test certain abnormal status codes. Through rewrite rules, you can elegantly perform API Mocking and boundary testing.

3.1 Scope Configuration (Scope)

When adding a rewrite rule, you need to specify the scope in which the rule takes effect to avoid accidentally affecting unrelated requests. The system provides an extremely easy configuration method, and you don't need to write complex matching conditions:

Select Domain/Host: You can quickly select from a dropdown list of target Hosts that have already been captured, or enter it manually. Wildcards are supported (e.g., *.example.com).
Select API (Path): After selecting the Host, you can directly select specific APIs from the list (Method and Path will be brought in automatically), or manually enter specific paths (supports * wildcard path matching, e.g., /api/v1/*).

💡 Efficiency Tip: If you select an existing API from the list, the system will automatically Prefill the subsequent Mock response templates or Headers for you, saving you a lot of configuration time!

3.2 Debugging Actions (Rewrite Action)

Redirect: Route the request to another address (for example, redirect production traffic to Localhost or a staging environment).
Mock Response: Do not send an actual network request, directly return your preset test data (JSON/XML). Supports configuring status codes (e.g., simulating 404, 500 exceptions), response headers, and response bodies.
Drop:
- Drop Request: Simulate a request that cannot be sent (e.g., network disconnection scenario).
- Drop Response: Simulate server unresponsiveness/timeout.
Delay: Artificially inject network delay, used to test the App's Loading interaction performance under weak network environments.
Modify Request/Response:
- Edit Header: Used to inject test Tokens into request headers or modify User-Agent.
- Replace Body: Completely replace the contents of the request body or response body.
- Regex Find and Replace Body: Perform fine-grained field replacement on JSON. For example, use regex to replace "status": "pending" with "status": "success" to test subsequent logic.

💡 Common Troubleshooting Guide:

Rule not taking effect: There is another rule with higher priority (recently added) overriding the current rule.

Regex replacement fails: JSON data often contains indents and spaces. If the regex does not account for whitespace characters (e.g., using \s*), it may cause the match to fail. It is recommended to use the built-in "Test" panel to verify the expression.

4. Advanced Custom Processing: JavaScript Scripts (Script)

For complex Mock scenarios that require dynamic calculation (such as timestamp signature calculation, dynamic data assembly), the scripting engine provides the highest level of programmable debugging capabilities.

4.1 Core Function Panels and Auxiliary Tools

In addition to manual coding, ApiCatcher provides powerful surrounding tools to help you complete script creation and verification:

AI Auto-generate Scripts: No need to write a single line of code by hand. You only need to input natural language instructions (e.g., "Help me change the value of the price field in the response body to 9.9, and add discount_tag: true"), and the built-in AI assistant can directly generate and fill in standard JS code for you.
Local Test Environment (Test Script): Before officially saving to take effect, you can directly click test. You can choose an actually captured request from the history to feed to the script, and the system will intuitively display the data comparison results before and after modification along with any error logs, ensuring your syntax is correct.
Remote Script Hosting (Remote Script): Supports directly entering a public http:// or https:// script URL. ApiCatcher will locally load and execute the cloud script, which is very helpful for uniformly deploying and maintaining public Mock rules within a team!

4.2 Script Core Functions

For how to write scripts, please read the documentation: APICatcher Scripting Feature Guide

You only need to implement predefined lifecycle functions:

// Process outgoing requests
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';
    }
    // Return actions: passthrough, modify, mock, drop
    return { action: 'modify', request: request };
}

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

4.2 Built-in Advanced APIs

localStore: Used for state maintenance across requests. For example, saving the authorization state in the login API and automatically injecting it in subsequent APIs.
- localStore.write('session_id', 'abc')
- var t = localStore.read('session_id')
httpClient: Supports sending additional network requests during script execution (used to sync external states or fetch dynamic configurations).
- var res = httpClient.get('https://api.ipify.org')

💡 Common Troubleshooting Guide:

Syntax or runtime errors: Use the built-in "Test Script" button to verify logic. You can use console.log("...") and view the output on the "Logs" page.

Lifecycle conflicts: If a request has already been Mocked or Dropped by a higher-priority "Rewrite Rule", it will no longer enter the subsequent script execution flow for that request.

5. Automated Testing: Combo Replay

Testing a single API cannot satisfy full business flow verification (e.g.: Login -> Get Authorization -> Query Info -> Submit Form). Combo Replay supports visual orchestration and automated regression of multiple associated APIs.

5.1 Configuration Steps

Add Nodes: Sequentially add business flow requests from the history to the canvas.
Establish Dependencies: Create directed edges between nodes to ensure requests are strictly executed in sequence according to their dependencies.
Parameter Mapping (Dependency Injection): Configure data flow. Dynamically inject specific fields from the response of an upstream API into downstream requests.

5.2 Parameter Mapping Configuration Details

Extraction Source: Can be extracted from upstream responseBody or responseHeader.
- Extraction Path: If it's a JSON response body, use JSON Path directly (e.g., data.session.token).
Injection Target: Can be injected into downstream requestHeader, queryParam, or requestBody.
Optional Prefix: Used for auto-completion of specific standards. For instance, if the extracted value is abc, but the standard requires sending Bearer abc in the header, simply fill in Bearer here to automatically concatenate it.

💡 Common Troubleshooting Guide:

Parameter not successfully extracted: Use the tree structure of the "Sample Response Body" built into the canvas node to click and select, avoiding format hierarchy errors caused by manual path writing.

6. Background Execution: Scheduled Tasks

With the background residency capability based on the VPN process, you can use "Scheduled Tasks" to regularly execute specific requests or Combo Replay rules. Typical Application Scenario: When developing or testing an e-commerce "flash sale" event, because the flash sale time window is extremely short, manual clicking often misses the exact moment. At this time, you can configure a scheduled task to let the API automatically request order submission at high frequency right before the flash sale starts, helping you fully verify the concurrency stability and business logic of the flash sale link.

6.1 Schedule Configuration (Schedule Type)

Cron Expression: Uses standard 5-field Cron syntax (e.g., */5 * * * * means execute every 5 minutes). You can use built-in AI assistance to generate it.
Custom Configuration: Supports fine-grained setting of start time, interval duration, and maximum number of executions.

6.2 Auto Terminate Conditions

Set termination conditions to avoid meaningless retries in abnormal situations, or to exit automatically after reaching the goal:

Match JSON Fields: For example, in the "flash sale testing" scenario, monitor the code field of the return result. Once code equals 200 (meaning successful purchase submission) or equals 400 (meaning inventory is empty and event ended), termination is triggered.
Regular Expression Matching: Perform full text matching on the response body. As long as character signatures like "msg": "Purchase successful" or "error": "Event has ended" are matched, the task will automatically stop completely.

💡 Common Troubleshooting Guide:

Task cannot run: iOS system has strict background controls. When memory is tight, the VPN process might be reclaimed by the system, and scheduled tasks will pause along with it.

No history records shown: Scheduled tasks are monitoring requests initiated directly by the underlying engine, and will not be recorded in the main App's regular "History". You need to view reports such as success rate and p95 in the task's exclusive "Execution History" panel.

Rule updates not taking effect: Scheduled tasks bind to a snapshot of the rule upon creation. If the original "Combo Replay" rule is changed, the scheduled task needs to be recreated.

7. Quality & Performance Troubleshooting: API Scan

Based on locally captured traffic records, it provides non-intrusive API quality, security compliance, and performance health checks. All analysis is completed entirely within the device's local memory loop.

7.1 Built-in Scan Engine

Sensitive Information Self-check: Supports detecting cleartext transmissions of phone numbers, ID cards, emails, and cloud service credentials (like AWS Keys, OpenAI API Keys), helping front-end and API designers discover data desensitization omissions early.
Abnormal Stack Leakage: Identifies uncarefully returned Java, Python, or SQL error call stacks in response bodies.
High-Frequency Call Analysis: Based on set thresholds (e.g., average request interval less than a specific milliseconds), troubleshoots whether there are redundant API calls caused by infinite loops or improper logic.
Time Consumption Evaluation: Aggregates and calculates p95 and p99 latencies for various APIs, assisting in locating backend performance bottlenecks.

7.2 Custom Quality Detection (Custom Scan)

You can write JS scripts to execute business-customized compliance checks.

Return Value Convention: If the function deems the request meets expectations, return null; if non-compliance is detected (e.g., response body too large, missing security headers), return a concise description (≤200 characters), and the system will automatically include it in the scan report.

💡 Common Troubleshooting Guide:

No results analyzed: Confirm whether the "Scan Scope (Host/Session)" actually contains valid JSON/API traffic records, rather than purely static resources. To ensure a good experience, there is a maximum record limit for a single scan.

8. Utility Tools: Encryption/Decryption & Desktop Sync

8.1 Developer Toolbox (Decrypt/Encrypt)

To deal with encrypted payload transmissions, common codec tools are built-in:

AES Decryption: Supports entering custom Key and Initial Vector (IV) to quickly decrypt and test Payloads.
Base64 / URL Encode / MD5 / SHA256.
Custom Processing: Supports writing single-execution JS snippets to perform data transformation on selected text.

8.2 Desktop Real-time Sync (Realtime Sync)

Usage: If you need to debug data with a broader view on a PC, you can seamlessly push captured data packets to the ApiCatcher Desktop application via WebSocket protocol. Configuration:

Enter the WebSocket address allocated within the local area network.
Be sure to pass "Test Connectivity" first to verify handshake success.
Troubleshooting: Ensure the mobile terminal has been granted "Local Network" permission, the PC firewall has allowed the corresponding port, and ensure both are on the same LAN subnet.