apimock-rs (API Mock)

Build a working REST API in seconds — without a backend.
Frontend blocked by an unfinished backend ? Need stable API responses for UI tests or offline development ?
Drop JSON files into a folder and your API immediately exists.

Mock APIs easily 🎈 — just JSON and go

If you’re building or testing APIs, this tool makes mocking painless. It’s super fast, efficient, and flexible when you need it to be. All you have to do to start up is just use folders and JSON without any config set.

• ❄️ Zero-config start.
• 🌬️ Fast to boot, light on memory.
• 🪄 File-based and rule-based matching. Scripting supported.

Why apimock-rs ?

• The backend is not ready yet.
• You need stable API responses for UI testing.
• You want offline development.
• CI tests require a predictable API.
• Your mock data is becoming large.

Handles real project scale

As your project grows, your mock API grows, too. Large mock datasets often cause problems:

• Slow startup
• High memory usage
• Crashes during UI testing
• Unstable CI runs

apimock-rs does not preload responses. Each response file is read only when a request arrives using non-blocking I/O. This keeps:

• Startup nearly instant
• Memory usage minimal
• Stable behavior under repeated requests

as validated with k6 load testing. You can run UI development and automated tests continuously without worrying about server instability.

📖 Documentation

For more details, 🧭 check out the docs.

Quick start

Easy to start with npm package.

# install into your app project
npm install -D apimock-rs
# and go
npx apimock

# just use folders and JSON
mkdir -p api/v1/
echo '{"hello": "world"}' > api/v1/hello.json
npx apimock

# response
curl http://localhost:3001/api/v1/hello
# --> {"hello":"world"}

You may also check it out with browser to visit http://localhost:3001/api/v1/hello .

You now have a running REST endpoint.

Vite project integration

An example of scripts section in package.json is as below.

concurrently is used to run the Vite and API mock servers simultaneously, while cross-env enables terminal output coloring. Before starting, ensure you run:

npm install -D concurrently cross-env

Edit package.json:

  "scripts": {
    "apimock": "npx apimock",
    "dev": "cross-env CLICOLOR_FORCE=1 concurrently \"vite\" \"npm run apimock\""
  }

Run:

npm run dev

npx apimock variation

Configuration reference

Everything below describes the TOML config files. Run npx apimock --init (or apimock --init) once to scaffold apimock.toml and apimock-rule-set.toml into the current directory, then tweak to taste.

apimock.toml — top-level file

[listener]
ip_address = "127.0.0.1"   # interface to bind
port       = 3001          # plaintext HTTP port

[listener.tls]             # optional — enables HTTPS
cert = "./cert.pem"
key  = "./key.pem"
# port = 3002              # optional — if omitted, HTTPS replaces HTTP on the port above

[log]
verbose = { header = true, body = true }

[service]
strategy             = "first_match"                # only value supported today
rule_sets            = ["apimock-rule-set.toml"]    # paths, resolved relative to this file
middlewares          = []                           # Rhai scripts, resolved relative to this file
fallback_respond_dir = "."                          # folder served when no rule matches

Rule-set schema — apimock-rule-set.toml

[prefix]                                       # optional
url_path    = "/api/v1/"                       # prepended to every rule's url_path
respond_dir = "apimock-rule-sets/@respond-dir" # prepended to every rule's file_path

[default]                                      # optional
delay_response_milliseconds = 0                # applied to every rule in this set unless overridden

[[rules]]
when.request.url_path = "complicated"
when.request.method   = "POST"
when.request.headers.authorization = { value = "Bearer eyJhb", op = "starts_with" }
when.request.headers.user          = { value = "user1" }                 # op defaults to "equal"
when.request.body.json."user.id"   = { value = "42" }
respond = { text = "Strictly authorized !" }

[[rules]]
when.request.url_path = { value = "/public/", op = "starts_with" }
respond = { file_path = "public/index.json", csv_records_key = "records" }

[[rules]]
when.request.url_path = ""
respond = { status = 403 }

when.request — match conditions (AND-ed together)

respond — response shape

Exactly one of file_path / text / status must be present. (text may be combined with status to set the response code.)

op — comparison operators

Every { value, op } structure accepts these op values. If op is omitted it defaults to equal.

Wildcard / glob syntax (wild_card)

The glob matcher supports exactly two metacharacters, matching the common case without the complexity of a full regex engine:

Examples:

This is NOT a regex. Sequences such as ., […], (…), +, ^, $ are matched literally.

JSONPath form (body.json and csv_records_key)

The JSONPath support is deliberately minimal — only the "object key" and "array index" forms, joined by .. This covers every real-world body-match need without exposing a full jsonpath engine that users would then have to learn.

If any segment is missing or has the wrong shape (e.g. a numeric segment against an object), the rule simply does not match — no error, because "missing" is a useful matchable condition.

prefix

default

Open-source, with care

This project is lovingly built and maintained by volunteers.
We hope it helps streamline your API development.
Please understand that the project has its own direction — while we welcome feedback, it might not fit every edge case 🌱

Acknowledgements

Depends on tokio / hyper / toml / serde / serde_json / json5 / console / rhai / thiserror / anyhow. In addition, mdbook (as to workflows).