Mocklantis Desktop App Guide

In the left sidebar, locate the Mock Servers section at the top. Click the + button next to "Mock Servers" to open the create server modal.

The modal has two tabs at the top. Select the method that fits your needs:

After filling in the required fields, click the "New Mock Server" button at the bottom of the modal.

If you created a Default server, it starts empty. You need to add endpoints manually.

Once your server has at least one endpoint, click the "Start Server" button in the top section.

What is Proxy?

Proxy feature allows you to forward unmatched requests to a real backend server. This is incredibly useful when you want to:

• Mock only specific endpoints while keeping others live
• Test your app with a mix of mock and real data
• Gradually migrate from a real API to mocks (or vice versa)
• Debug specific endpoints without affecting the entire API

How Does It Work?

How to Use Proxy

Proxy Status in Sidebar

When proxy is enabled, you can easily see its status in the sidebar under your server name:

This gives you a quick overview of which servers have proxy enabled without opening settings.

⚡ Dynamic Routing - No Restart Needed!

Mocklantis uses dynamic routing for proxy settings. This means:

• Instant activation: Proxy settings apply immediately after saving
• No downtime: Your mock server keeps running while settings change
• Hot-swap: Switch between proxy targets without interrupting active connections
• Toggle on-the-fly: Enable/disable proxy anytime during testing

📚 Real-World Example

📊 Request Flow

Incoming Request
      │
      ▼
┌─────────────────┐
│  Check Method   │
│  (GET, POST...) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     No Match      ┌─────────────────┐
│  Check Path     │ ─────────────────▶│  Proxy Enabled? │
│  Variables      │                   └────────┬────────┘
└────────┬────────┘                            │
         │                           ┌─────────┴─────────┐
         │                           │                   │
         ▼                          Yes                  No
┌─────────────────┐                  │                   │
│  Check Query    │                  ▼                   ▼
│  Parameters     │         ┌───────────────┐   ┌───────────────┐
└────────┬────────┘         │ Forward to    │   │ Return 404    │
         │                  │ Target URL    │   │ "No mock      │
         ▼                  └───────────────┘   │  matched"     │
┌─────────────────┐                             └───────────────┘
│  Match Found!   │
│  Return Mock    │
│  Response       │
└─────────────────┘

Quick Comparison

Random variables allow you to generate dynamic, random data in your request and response bodies at runtime. Use the format {{random.type}} in your response body.

{
  "id": "{{random.uuid}}",
  "email": "{{random.email}}",
  "name": "{{random.name}}",
  "age": {{random.number}},
  "ipAddress": "{{random.ip}}",
  "createdAt": "{{random.date}}"
}

{
  "id": "a3d5f7b9-1234-5678-9abc-def012345678",
  "email": "[email protected]",
  "name": "Alice Johnson",
  "age": 7845,
  "ipAddress": "192.168.1.147",
  "createdAt": "2024-08-15"
}

📊 HTTP Status Codes

Every HTTP endpoint can return any valid HTTP status code. Mocklantis supports all standard status codes from 200 to 599. Simply click on the status selector in the Response section to choose from popular codes like 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error, and more.

The status selector is searchable - you can type the code number or the status text to quickly find what you need. For example, search "unauthorized" to find 401, or search "403" to find Forbidden.

📄 Request Body Matching

By default, Mocklantis returns your configured response regardless of what's in the request body. But sometimes you want different responses based on the request payload. That's where Request Body Matching comes in.

In the Request → Body tab, you'll find a "Match Body" checkbox. When enabled, Mocklantis will only return your mock response if the incoming request body matches what you specified (as JSON). This is perfect for testing different scenarios - for example, returning success for valid login credentials and error for invalid ones.

If no endpoint matches the request body, Mocklantis returns the first endpoint with "Match Body" disabled, or a 404 if all have matching enabled.

🏷️ Request Header Matching

Similar to body matching, you can also match requests based on their headers. In the Request → Headers tab, enable the "Match Headers" checkbox to require specific headers in the incoming request.

This is useful for testing authentication flows (matching Authorization headers), API versioning (matching Accept headers), or any scenario where different headers should trigger different responses.

🔍 Query Parameter Matching

Query parameters can be validated in two ways: type validation and exact value matching. In the Request → Query Params tab, you can define expected query parameters and choose whether to match their type or exact value.

When "Match Query Params" is enabled, Mocklantis uses a scoring algorithm to find the best matching endpoint. Exact value matches score higher than type matches. If multiple endpoints match, the one with the highest score wins. This allows you to create generic fallback endpoints and specific ones for particular query parameter values.

More details about query parameter types and validation can be found in the Query Parameters section below.

🎨 Automatic Content-Type Detection

Mocklantis automatically detects and sets the Content-Type header based on your request and response body content. When you type JSON in the body editor, it automatically adds Content-Type: application/json to the headers. The same works for XML content.

The Monaco editor (used for body editing) also provides syntax highlighting, validation, and formatting based on the detected content type. This makes it easy to work with JSON and XML responses without manually configuring everything.

⚙️ Response Configuration

Each HTTP endpoint has a comprehensive response configuration. In the Response section, you can set:

• Status Code: Any HTTP status from 200 to 599
• Response Delay: Simulate network latency in milliseconds (0-60000ms)
• Response Body: JSON, XML, plain text, or any content with syntax highlighting
• Response Headers: Custom headers returned with the response

The response body supports dynamic variables using the {{random.*}} syntax. For example, {{random.number(1,100)}} generates a random number between 1 and 100 each time the endpoint is called. More details about random variables can be found in the Random Variables section below.

Request Headers

Validate incoming request headers to ensure clients send the correct headers. Enable Match Request Headers toggle to activate validation.

Response Headers

Add custom headers to your mock responses. Useful for CORS, caching, content-type, and more.

Real-World Use Cases

{
  "userId": "12345",
  "name": "John Doe",
  "email": "[email protected]"
}

{
  "error": "Unauthorized",
  "message": "Missing or invalid authentication token"
}

{"name": "John", "age": 30}

<user>
  <name>John</name>
  <age>30</age>
</user>

What is State Machine?

State Machine (also called Scenarios) enables stateful mock behavior where your HTTP endpoints respond differently depending on the current state of a scenario. Instead of returning the same response every time, endpoints can follow a flow of states.

This is essential for testing multi-step workflows where the API behavior changes over time: user registration flows, payment processing, order lifecycles, authentication sequences, and more.

    ┌─────────────────────────────────────────────────────────────────────────────┐
    │                         STATE MACHINE EXAMPLE                                │
    │                           Order Processing                                   │
    └─────────────────────────────────────────────────────────────────────────────┘

                              ┌─────────────┐
                              │   Initial   │
                              │  (Pending)  │
                              └──────┬──────┘
                                     │
                                     ▼
                              ┌─────────────┐
                              │  Confirmed  │
                              └──────┬──────┘
                                     │
                        ┌────────────┴────────────┐
                        │                         │
                        ▼                         ▼
                 ┌─────────────┐          ┌─────────────┐
                 │  Shipped    │          │  Cancelled  │
                 └──────┬──────┘          └─────────────┘
                        │
                        ▼
                 ┌─────────────┐
                 │  Delivered  │
                 └─────────────┘

    GET /api/orders/123 returns different response based on current state:

    • Initial    → { "status": "pending", "canCancel": true }
    • Confirmed  → { "status": "confirmed", "estimatedDelivery": "..." }
    • Shipped    → { "status": "shipped", "trackingNumber": "..." }
    • Delivered  → { "status": "delivered", "deliveredAt": "..." }
    • Cancelled  → { "status": "cancelled", "refundStatus": "..." }

When to Use State Machine

Creating a Scenario

Visual Flow Graph

The flow graph is a powerful visual editor that lets you design your state machine with drag-and-drop simplicity. No code required - just draw your workflow.

Binding Endpoints to Scenarios

After creating a scenario, you need to bind HTTP endpoints to it. Each bound endpoint can return different responses based on the scenario's current state.

State Responses Configuration

Each state response defines what the endpoint returns when the scenario is in that particular state.

{
  "orderId": "123",
  "status": "shipped",
  "trackingNumber": "TRK-789456",
  "carrier": "FedEx",
  "estimatedDelivery": "2024-01-15"
}

Advance State Control

One of the most powerful features of State Machine is the "Advance State" checkbox. This controls whether hitting an endpoint advances the scenario to the next state or keeps it at the current state.

Linear vs Branching Flows

Mocklantis supports two types of state advancement: linear chains and branching flows.

Initial → Confirmed → Shipped → Delivered

Each state has ONE next state.
"Advance State" checkbox: enabled
No need to specify nextState.

         ┌→ Approved
Pending ─┤
         └→ Rejected

State "Pending" has TWO next states.
Each state response must specify:
  nextState: "Approved" or "Rejected"

How State Advancement Works

    ┌─────────────────────────────────────────────────────────────────────────────────────┐
    │                          STATE ADVANCEMENT FLOW                                      │
    └─────────────────────────────────────────────────────────────────────────────────────┘

                                    ┌─────────────────┐
                                    │ Request arrives │
                                    └────────┬────────┘
                                             │
                                             ▼
                                ┌─────────────────────────┐
                                │ Match HTTP Endpoint     │
                                │ (bound to scenario)     │
                                └────────────┬────────────┘
                                             │
                                             ▼
                                ┌─────────────────────────┐
                                │ Read current state      │
                                │ from scenario           │
                                └────────────┬────────────┘
                                             │
                                             ▼
                                ┌─────────────────────────┐
                                │ Find state response     │
                                │ matching current state  │
                                └────────────┬────────────┘
                                             │
                                             ▼
                                ┌─────────────────────────┐
                                │ Return response         │
                                │ (status, body, headers) │
                                └────────────┬────────────┘
                                             │
                                             ▼
                                ┌─────────────────────────┐
                                │ "Advance State"         │
                                │ checkbox enabled?       │
                                └────────────┬────────────┘
                                             │
                              ┌──────────────┴──────────────┐
                              │                             │
                             YES                            NO
                              │                             │
                              ▼                             ▼
                ┌─────────────────────────┐     ┌─────────────────────────┐
                │ "Next State" specified  │     │ Stay in current state   │
                │ in state response?      │     │ (no advancement)        │
                └────────────┬────────────┘     └─────────────────────────┘
                             │
               ┌─────────────┴─────────────┐
               │                           │
              YES                          NO
               │                           │
               ▼                           ▼
    ┌─────────────────────┐    ┌─────────────────────────────┐
    │ Transition to       │    │ Count outgoing transitions  │
    │ specified nextState │    │ from current state          │
    └─────────────────────┘    └──────────────┬──────────────┘
                                              │
                                 ┌────────────┴────────────┐
                                 │                         │
                              1 transition            0 or 2+ transitions
                                 │                         │
                                 ▼                         ▼
                    ┌─────────────────────┐    ┌─────────────────────────┐
                    │ Auto-advance to     │    │ Stay in current state   │
                    │ that single state   │    │ (cannot auto-decide)    │
                    └─────────────────────┘    └─────────────────────────┘

Real-Time State Display

Mocklantis shows you the current state of your scenarios in real-time. No need to refresh or poll - the UI updates instantly when state changes.

Real-World Example Scenarios

States:
                   ┌→ ManagerApproved ─┬→ DirectorApproved → Finalized
Draft → Submitted ─┤                   └→ DirectorRejected
                   └→ ManagerRejected

Resetting a Scenario

When you need to start over or run tests again, you can reset a scenario back to its "Initial" state.

Webhooks allow you to automatically trigger HTTP requests to external services when your mock endpoints are called. This enables you to simulate real-world integrations, test notification systems, and create realistic async workflows.

Client Request → Mock Response Sent → Webhook Triggered (async)
                        ↓                       ↓
                   Immediate              External Service
                   Response               (Slack, Payment, etc.)

Creating a Webhook

Binding Webhooks to Endpoints

There are two ways to create a binding between a webhook and an endpoint:

Webhook Configuration

Template Variables

Extract values from the original HTTP request and include them in your webhook payload using {{category.key}} syntax.

{
  "event": "order_created",
  "timestamp": "{{request.timestamp}}",
  "data": {
    "orderId": "{{request.path.id}}",
    "customer": "{{request.body.customer.name}}",
    "total": {{request.body.total}}
  }
}

Webhook History & Monitoring

Every webhook execution is logged and visible in the Response tab of your webhook. Monitor, debug, and verify that your webhooks are working correctly in real-time.

Testing Webhooks

Mocklantis provides a "Try" button to manually test webhooks without triggering them from an endpoint.

Retry Logic

Configure automatic retries for webhooks that fail due to network issues or temporary service outages.

Attempt 1: Failed (timeout)
    ↓ Wait retryDelay (1000ms)
Attempt 2: Failed (500 error)
    ↓ Wait retryDelay (1000ms)
Attempt 3: Success! (200 OK)

Troubleshooting

Summary