Table of Contents

• Installation
• Quick Start
• CLI Usage
  • Commands
  • Options
  • API Method Syntax
• Configuration File
  • Top-Level Properties
  • Endpoint Properties
  • Template and Data Behavior
  • Dynamic Token Reference
• Configuration Website
• Examples
• Troubleshooting
• Authors

Installation

npm install -g ntropi

Quick Start

# 1) Create config
ntropi --api users posts --delay 500 --failure-rate 10

# 2) Run server
ntropi run

By default, Ntropi starts at http://localhost:8008. If port 8008 is occupied, it automatically tries the next free port.

CLI Usage

Commands

# Generate or update config (default: ntropi-config.json)
ntropi [options]

# Run server using default config file
ntropi run

# Same as above using flag
ntropi --run

Options

| Option | Shorthand | Description | | --- | --- | --- | | --help | - | Show help output | | run | - | Run the mock server | | --run | -r | Run the mock server | | --api <values...> | -a | Endpoints to generate/update | | --delay <num> | -d | Response delay in milliseconds (integer, >= 0) | | --failure-rate <num> | -f | Failure percentage (0 to 100) | | --config <file> | -c | Config file path | | run --editor-only | - | Start only the configuration website (no mock endpoints) |

API Method Syntax

You can set endpoint methods directly in --api values:

# Default method is GET
ntropi --api users products

# Explicit method
ntropi --api users:POST orders:DELETE

# Shorthand methods
# G=GET, P=POST, U=PUT, D=DELETE, H=PATCH
ntropi --api users:G orders:P profile:U health:D patch-test:H

Configuration File

Default file: ntropi-config.json

{
  "localhost": true,
  "endpoints": [
    {
      "path": "/api/users",
      "method": "GET",
      "data": [
        { "id": 1, "name": "$name" },
        { "id": 2, "name": "$name" }
      ],
      "delay": 300,
      "failureRate": 5,
      "cacheSize": 5
    }
  ]
}

Top-Level Properties

• endpoints (required): array of endpoint definitions.
• localhost (optional):
  • true or omitted: bind to 127.0.0.1.
  • false: bind to 0.0.0.0 for LAN/network access.

Endpoint Properties

• path (required): route path, must start with /.
• method (required): one of GET, POST, PUT, DELETE, PATCH.
• data (required): source data used for response generation.
• delay (optional): non-negative number in milliseconds.
• failureRate (optional): number in range 0..100.
• cacheSize (optional): positive integer response cache size.
• template (optional): object template that maps placeholders to data.

Template and Data Behavior

• If template is not provided:
  • array data: one top-level item is randomly selected (token resolved if present).
  • object/string data: returned directly (after token resolution).
• If template is provided:
  • data must be a non-empty array.
  • indexed placeholders like $1, $2 refer to array positions.
  • nested template objects/arrays are supported.

Template example:

{
  "endpoints": [
    {
      "path": "/api/profile",
      "method": "GET",
      "data": [
        ["active", "inactive"],
        { "name": "$name", "age": "$int(18-40)" }
      ],
      "template": {
        "status": "$1",
        "user": "$2"
      },
      "delay": 0,
      "failureRate": 0
    }
  ]
}

Custom Dataset Generator

We have built a powerful custom dataset generator designed to deliver instant, ready-to-use datasets tailored to your exact specifications. Simply define your parameters, set your desired values, and generate structured data on demand, no manual effort required.

Dynamic Token Reference

Supported value generators in data strings:

• $name
• $string(min-max) or $string(n)
• $int(min-max) or $int(n)
• $float(min-max,decimals)
• $bool
• $date(format) (or $date for ISO timestamp)
• $uuid

Escape tokens with \\$ to keep them as literal text.

Configuration Website

When you run Ntropi, it also serves a configuration website at the server root.

ntropi run

Then open:

• http://localhost:8008/ (or the printed port)

Editor-only mode:

ntropi run --editor-only

This starts only the configuration website and management APIs, without generating mock API endpoints.

Examples

# Basic endpoints
ntropi --api users posts comments

# With delay and failures
ntropi --api orders payments --delay 1200 --failure-rate 25

# Mixed methods
ntropi --api users:G users:POST users:PUT users:D

# Custom config file
ntropi --api products --config staging.json
ntropi run --config staging.json

Troubleshooting

Config validation error

Check that:

• each endpoint has path, method, data
• path starts with /
• method is valid
• delay >= 0 and failureRate is in 0..100

Port already in use

Ntropi automatically increments the port until it finds a free one.

Endpoint not changing after edit

Ntropi hot-reloads config file changes. If you changed endpoint path/method, the server restarts automatically. For value-only changes (like delay, failureRate, data), endpoints keep running and use new values on next request.

Authors

• Amitrajeet Konch
• Pushpender Singh