Mockly - Tiny API Mock Server

Mockly is a small, file-based API mock server for local testing. It is designed to allow replacing an API server when testing any tool that uses a JSON API.

Configuring endpoints can be done either by placing JSON files in a simple directory structure, or by defining routes in a lightweight index.yml.

$ gem install mockly

Mockly is also available as a docker image:

# Pull the image
$ docker pull dannyben/mockly

# Run the mockly command line
$ docker run --rm -it dannyben/mockly --help

# Start the server
$ docker run --rm -it \
    -p 3000:3000 \
    -v $PWD/mocks:/app/mocks \
    dannyben/mockly

# docker-compose.yml
services:
  web:
    image: dannyben/mockly
    volumes:
      - ./spec/fixtures/mocks:/app/mocks
    ports:
      - 3000:3000

$ alias mockly='docker run --rm -it -p 3000:3000 -v $PWD/mocks:/app/mocks dannyben/mockly'

Mocks live under a single mocks/ folder. For a request path, Mockly looks for JSON files in this order (first match wins):

1. mocks/<dir>/<method>-<name>.json
2. mocks/<dir>/<name>/<method>.json
3. mocks/<dir>/<name>.json

Quick diagram:

mocks/
  get.json
  get-users.json
  users/
    get.json
    post.json
  chat/
    completions.json
  assets/
    image.jpg

Examples:

• GET / → mocks/get.json
• GET /users → mocks/get-users.json (or mocks/users/get.json, or mocks/users.json)
• POST /users → mocks/post-users.json (or mocks/users/post.json, or mocks/users.json)
• GET /chat/completions → mocks/chat/completions.json

Static files are also supported: if an exact file exists under mocks/, it is served as-is (e.g. GET /assets/image.jpg → mocks/assets/image.jpg).

You can define simple routes in mocks/index.yml (or mocks/index.yaml) using keys in the form METHOD /path.

GET /:
  status: running

GET /users:
  users:
    - id: 1
      name: Jane

POST /login:
  token: abc123

Route values can be objects, arrays, scalars, booleans, etc. Responses are returned as JSON.

Lookup precedence is:

1. Exact static file in mocks/
2. JSON file candidates in mocks/
3. Route in index.yml / index.yaml
4. 404 JSON error

If both mocks/index.yml and a project-root index.yml exist, the one in mocks/ is preferred.

If you experience any issue, have a question or a suggestion, or if you wish to contribute, feel free to open an issue.