#json-response #mocking #url-path #testing #http-response #testing-http #https

app apimock

API mock Server generating HTTP/JSON responses written in Rust

4 stable releases

new 2.1.0 May 17, 2024
2.0.5 May 16, 2024
2.0.4 Mar 5, 2024

#1 in #url-path

Download history 299/week @ 2024-03-01 52/week @ 2024-03-08 6/week @ 2024-03-15 14/week @ 2024-03-29

311 downloads per month

ISC license

768 lines


Mocking helper to develop microservices and APIs. hyper-based HTTP server generating REST responses containing JSON ones. Written in Rust.



Aims to help developers to easily get responses from dummy API, especially microservice API, according to several paths. Each single executable on Win/Mac/Linux are available, thanks to Rust and their cross-platform support. Releases are "out-of-the-box" coming with default config apimock.toml.

* Renamed from json-responder. Now more than returning JSON data.


Server started to listen:

server starts

curl test result:

server responds

Designed in mind with

  • Performance
    • Fast speed, low memory consumption.
  • Easy setup/usage
    • Built as single (and small) executable, integrated configuration. (No need to write scripts, config-less mode is also supported.)
  • Cross-platform support


  • GET / POST methods
  • Multiple paths
  • Multiple .json/.json5 files treated as JSON Response
  • Can switch data directory paths manually in testing via specific HTTP request to make json responses flexible
  • Dynamic path resolution with dyn_data_dir
  • Custom responses codes (HTTP 3xx as redirects and 4xx and 5xx as errors)
  • Custom headers and their reusabliblity
  • Validates configuration: Missing JSON files, duplicate paths etc.
  • Prints out routing at startup


  • Releases are available.
    • Create your configuration file (./apimock.toml by default) and run apimock with it.
  • Via cargo: cargo install apimock
  • Also able to build manually.
    • Run cargo build --release. Then run to start the server: ./target/release/apimock.
    • Alternatively, just running cargo run works.

Running apimock without both apimock.toml and apimock-data/ directory results in always option activated.

How startup works

    subgraph Startup workflow
        direction TB
        A[config mode if apimock.toml exists] --> B[config-less mode if apimock-data dir exists]
        B --> C[`always` mode : fixed response]




port = 3001
dyn_data_dir = "apimock-data"
# always = "{ greetings: \"Hello, world.\" }"

data_dir = "tests"
data_dir_query_path = "@@"
path_prefix = "api/v1"

cookie_1 = { key = "Set-Cookie", value = "a=b; c=d" }
redirect_1 = { key = "Location", value = "/api/v1/home" }

# required when `always` is not specified
[url.paths] # `path_prefix` works
"home" = "home.json"
# "some/path" = "api.json5"
# custom headers
"some/path/w/header" = { src = "home.json", headers = ["cookie_1"] }
# errors / redirects * `code` must be defined as **unsigned integer** (instead of String)
"error/401" = { code = 401 }
"error/api-403" = { code = 403 }
"redirect/302" = { code = 302, headers = ["redirect_1"] }

[url.raw_paths] # `path_prefix` doesn't work
"/" = { text = "{ Hello: world }", code = 301, headers = ["cookie_1", "redirect_1"] }



If set, URL path without statically defined path matched is converted to file path in this directory. Server tries to find it out as either .json or .json5. When found, server returns the content as JSON response.
Default: empty

It works even without config toml. It is config-less mode.


Data directory used as where to look up files when HTTP response is built.
Default: executable directory


Data directory can be switched manually via HTTP request. Access to to get the current value. Access to to change it. Default: "@@"


Static paths are dealt with as those who have the prefix. Convenient when your service has path prefix.
Default: empty


HTTP headers such as Authorizaton: xxx on auth and Location: xxx on redirection. You can reuse them and easily attach headers in url.paths by defining here.
Default: None


The key, the left-hand side, is URL path. The right-hand one is response definition. Response definition consists of four optional parts: code as HTTP code, headers as HTTP headers keys defined in url.headers, src as data source file relative path in url.data_dir and text as direct body text instead of src. For example:

"url_path" = { code = 200, headers = ["header_key_1"], src = "response_1.json" }

It is able to omit code and headers. For example:

"url_path" = "response_1.json"

It means src and it's far simpler. code and headers are dealt with as their default: 200 as OK and no custom headers.

Only when either src or text is defined, the response Content-Type is set as application/json.


Not affected by url.path_prefix. Everything else is the same to url.paths.


-c / --config

Config file path. default: apimock.toml

After server started

What is modifiable:

  • content of path data src: .json / .json5

What is NOT modifiable:

  • always config
  • routing on paths
  • code / headers / data text on each path

How response works

    subgraph Response workflow
        direction TB
        A[`always` is activated ?] --> B[`data_dir_query_path` accessed ?]
        B --> C[`path.urls` have the path ?]
        C --> D[exists in `dyn_data_dir` ?]

How to embed to development environment

With Node.js project, scripts in package.json is available. For example, run npm run apimock with package.json written in as below:

  "scripts": {
    "apimock": "./apimock"


Depends on:

tokio / hyper / toml / serde / serde_json / json5 / console. In addition, mdbook (as to workflows)


~272K SLoC