Mock Servers

Mock Servers

ApiArk includes local mock servers that run entirely on your machine — no cloud, no usage limits, no external dependencies.

---

Overview

Mock servers simulate API responses so you can:

• Develop frontend without waiting for the backend
• Test error handling with controlled failure responses
• Demo your API without deploying anything
• Run integration tests in CI/CD without external services

---

Quick Start

1. Right-click a collection in the sidebar
2. Select Start Mock Server
3. Choose a port (default: 4000)
4. The mock server starts on http://localhost:4000

All requests in the collection become mock endpoints using their saved response examples.

---

How It Works

Each request in your collection with response examples becomes a mock endpoint:

# users/get-all-users.yaml
name: Get All Users
method: GET
url: "{{baseUrl}}/api/users"

examples:
  - name: Success
    status: 200
    headers:
      Content-Type: application/json
    body: |
      {
        "users": [
          {"id": "1", "name": "John Doe", "email": "john@example.com"},
          {"id": "2", "name": "Jane Smith", "email": "jane@example.com"}
        ],
        "total": 2
      }
  - name: Empty
    status: 200
    body: |
      {"users": [], "total": 0}
  - name: Unauthorized
    status: 401
    body: |
      {"error": "Invalid or expired token"}

When the mock server is running:

curl http://localhost:4000/api/users
# Returns the "Success" example by default

Selecting Examples

# Use the X-Mock-Example header to select a specific example
curl -H "X-Mock-Example: Unauthorized" http://localhost:4000/api/users
# Returns the 401 response

---

Dynamic Responses with Faker.js

Generate realistic fake data using Faker.js in your mock responses:

examples:
  - name: Dynamic User
    status: 200
    headers:
      Content-Type: application/json
    body: |
      {
        "id": "{{$uuid}}",
        "name": "{{$faker.person.fullName}}",
        "email": "{{$faker.internet.email}}",
        "avatar": "{{$faker.image.avatar}}",
        "createdAt": "{{$isoTimestamp}}"
      }

Every request returns a different random user.

Available Faker Categories

Category	Examples
person	fullName, firstName, lastName, jobTitle
internet	email, url, ip, userAgent, password
phone	number
address	streetAddress, city, country, zipCode
company	name, catchPhrase, bs
finance	amount, currencyCode, accountNumber
date	past, future, recent, birthdate
lorem	sentence, paragraph, words
image	avatar, url
string	uuid, alphanumeric
number	int, float

---

Latency Simulation

Simulate slow responses to test timeout handling:

examples:
  - name: Slow Response
    status: 200
    delay: 3000   # 3 second delay
    body: |
      {"status": "ok"}

Random Latency

examples:
  - name: Variable Latency
    status: 200
    delay:
      min: 100
      max: 2000
    body: |
      {"status": "ok"}

---

Error Simulation

Test how your app handles various error conditions:

examples:
  - name: Server Error
    status: 500
    body: |
      {"error": "Internal server error", "code": "ERR_INTERNAL"}

  - name: Rate Limited
    status: 429
    headers:
      Retry-After: "30"
    body: |
      {"error": "Too many requests", "retryAfter": 30}

  - name: Timeout
    status: 408
    delay: 30000   # Simulates a timeout
    body: ""

---

Mock Server Configuration

Port Selection

Default: 4000
Range: 1024-65535

CORS

Mock servers include permissive CORS headers by default — your frontend can call them from any origin.

Path Matching

• URL paths from your requests are used as routes
• Path parameters (:id) are matched as wildcards
• GET /api/users/:id matches GET /api/users/123

---

Architecture

Mock servers use axum (Rust HTTP framework) running on a local tokio task:

• Lightweight — adds minimal RAM overhead
• Fast — native Rust performance
• Independent — runs alongside the main app, doesn't block the UI
• Multiple mock servers can run simultaneously on different ports

---

Tips

• Use mock servers during frontend development to avoid backend dependencies
• Create error examples to test your error handling UI
• Use Faker.js for realistic demo data
• Set up latency simulation before performance testing
• Mock servers work offline — no internet required