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