Mock Files

A mock file is a single JSON or YAML file that describes one HTTP endpoint. Mimic reads every .json, .yaml, and .yml file in the mounted mocks directory and turns each one into a route.

File location

Inside the container, mocks live at /app/mocks. With the recommended Docker setup, you mount your local ./mocks folder there:

-v $(pwd)/mocks:/app/mocks:ro

The :ro flag mounts it read-only — Mimic never writes to your mocks folder.

Where Mimic actually reads from, in order:

1. MIMIC_MOCKS_DIR, if set — a directory or a single mock file. Used verbatim: a path that doesn’t exist is reported as missing rather than silently replaced by a default.
2. /app/mocks, if it exists — the Docker image’s mount point, so the command above resolves exactly there.
3. ./mocks, relative to the working directory — what cargo run, make dev, or a release build picks up from a clone of the repo.

The resolved directory is logged at startup, and a run that registers no mocks says which of the two reasons applies — the directory isn’t there, or it’s there and holds no mock files.

Anatomy of a mock file

Here is a complete mock with every common field:

{
  "method": "GET",
  "path": "/users",
  "status": 200,
  "consume_body": false,
  "response": {
    "users": [
      { "id": 1, "name": "Alice" }
    ]
  }
}

Required fields

Field	Type	Description
method	string	HTTP method: GET, POST, PUT, DELETE, PATCH, etc.
path	string	URL path the request must hit (e.g. /users, /api/v1/orders).
status	number	HTTP status code to return (200, 201, 404, 500, …).
response	any	The JSON body to return. Can be an object, array, string, number, or null.

Optional fields

Field	Type	Default	Description
consume_body	boolean	false	Whether Mimic should read the request body. Set to true for file uploads. See File Uploads.
query_params	object	—	Match against query string parameters. See Query Parameters.
headers	object	—	Match against request headers. See Headers.
body	object	—	Match against the request body. See Request Body.
response_headers	object	—	Custom response headers (CORS, Location, non-JSON content types, …). See Custom Response Headers.
response_file	string	—	Serve the body from a file next to the mock instead of response. See File-Backed Responses.
template	boolean	false	Enable {{ }} templating inside a response_file body.
delay_ms	number or object	—	Simulate latency: a fixed delay or a random range. See Response Delays.
sequence	array	—	Return a different response on each successive call. See Stateful Sequences.
tags	string[]	—	Restrict this mock to a scenario — matchable only when one of its tags is active.

The path field can also use :id / {id} segments to match a whole family of URLs with one mock — see Path Parameters — and any string inside response can pull data from the request via {{ }} templates — see Response Templating.

YAML mocks

The same shape works as .yaml or .yml, and either extension can sit alongside .json files in the same directory — pick per file whichever reads better:

# Comments are why this one is YAML: worth documenting, not worth an
# escaped multi-line string.
method: GET
path: /users
status: 200
response:
  users:
    - id: 1
      name: Alice Johnson
      email: [email protected]

YAML’s block scalars (|) are the other reason to reach for it — a multi-line HTML/XML body with no \n escaping:

method: GET
path: /docs
status: 200
response:
  html: |
    <html>
      <body>Static docs page</body>
    </html>

JSON stays the default and first-class format; YAML is an alternative for files where either of the above is worth it, not a replacement.

Naming and organizing files

The filename has no effect on routing — Mimic only cares about the method and path fields inside the file. That said, descriptive names make your mocks folder readable. A common convention:

mocks/
├── get_users.json
├── get_user_by_id.json
├── post_login.json
├── post_logout.json
└── delete_user.json

You can also use subdirectories — Mimic scans recursively:

mocks/
├── auth/
│   ├── login.json
│   └── logout.json
└── users/
    ├── list.json
    └── create.json

How Mimic discovers mocks

On startup, Mimic walks the mocks directory, parses every .json file, and builds a route table in memory. The /health endpoint reports how many mocks were loaded:

curl http://localhost:8080/health
# {"status":"healthy","mocks_loaded":5,"service":"mimic"}

If a file fails to parse — invalid JSON/YAML, missing required field — Mimic logs an error and skips that file. The rest still load, and via hot reload the broken file’s own route keeps serving its last successfully-loaded response until the file is fixed. Set RUST_LOG=debug to see exactly which file was rejected and why.

Mock files load in a fixed order — depth-first, alphabetical by full path — so which of several mocks registered for the same METHOD:path wins a tie (see Match Priority) is a function of their file names alone, not load order. It doesn’t vary between filesystems, between a fresh clone and a rebuilt image, or after an unrelated file is added to the directory.

Two files claiming the same route also don’t collide with Mimic’s own routes: /health and everything under /admin are matched before the mock set — see Reserved Endpoints for what’s reserved and how to free a path if your API needs it.

Caution

Two mocks with the same method and path will both be loaded. When a request comes in, Mimic uses its match priority scoring to decide which one wins. This is intentional — it lets you have multiple variants of the same endpoint differentiated by query params, headers, body content, or an active scenario tag.

What happens when nothing matches

If no mock matches an incoming request, Mimic returns a 404 with a structured error:

{
  "error": "mock not found",
  "method": "GET",
  "path": "/some/undefined/path"
}

This is useful for spotting typos and missing mocks during development.