api-mock-core

Instant mock REST server from a JSON file. Zero config, zero wait.

The Problem

You're building a frontend. The backend isn't ready. You're blocked.

api-mock-core kills that block in one command.

Quick Start

# No installation needed — just run it
npx api-mock-core

# Or scaffold a sample file first
npx api-mock-core init
npx api-mock-core

Your mock server is now live at http://localhost:3000 with full CRUD on all routes defined in api.json.

api.json Format

{
  "/users": [
    { "id": 1, "name": "Alice", "email": "[email protected]", "role": "admin" },
    { "id": 2, "name": "Bob",   "email": "[email protected]",   "role": "user"  }
  ],
  "/products": [
    { "id": "p1", "name": "Widget", "price": 29.99, "stock": 100 }
  ]
}

That's it. Every key is a route. Every value is the initial dataset.

Auto-Generated Endpoints

For every route /resource in your JSON, api-mock-core creates:

| Method | URL | Description | |----------|------------------------|---------------------------------------| | GET | /resource | List all items | | GET | /resource/:id | Get one item by ID | | POST | /resource | Create a new item (auto-generates ID) | | PUT | /resource/:id | Full replace | | PATCH | /resource/:id | Partial update | | DELETE | /resource/:id | Delete item |

Query Parameters

Filtering

GET /users?role=admin
GET /users?name=ali           # case-insensitive substring match
GET /users?role=user&active=true  # multiple filters (AND)

Full-text Search

GET /users?_q=alice           # searches all fields

Sorting

GET /users?_sort=name&_order=asc
GET /products?_sort=price&_order=desc

Pagination

GET /users?_page=1&_limit=10

Pagination headers returned:

• X-Total-Count — total items matching filters
• X-Page — current page
• X-Limit — items per page
• X-Total-Pages — total pages

CLI Options

Usage: npx api-mock-core [file] [options]

Arguments:
  file                  Path to api.json (default: api.json)

Options:
  -p, --port <number>   Port to listen on (default: 3000)
  -w, --watch           Hot-reload on file changes
  --no-cors             Disable CORS headers
  --open                Open browser automatically
  --no-log              Suppress HTTP access logs
  --quiet               Suppress all non-error output
  --delay <ms>          Add artificial delay to all responses
  --read-only           Disable POST/PUT/PATCH/DELETE (GET only)
  --host <host>         Hostname/IP to bind (default: 0.0.0.0)
  --id-field <field>    Primary key field name (default: id)
  -v, --version         Output version number
  -h, --help            Display help

Pro Options:
  --auth <key>          Require X-API-Key header on all requests
  --share               Expose server via public tunnel URL
  --license <key>       Activate Pro features

Sub-Commands

# Scaffold a sample api.json in current directory
npx api-mock-core init

# Validate your api.json
npx api-mock-core validate api.json

# List all endpoints in a file
npx api-mock-core list api.json

Internal Utility Endpoints

| Endpoint | Description | |----------------|------------------------------------------| | GET /__routes | List all registered endpoints | | GET /__health | Server health check (uptime, memory) | | GET /__version| Version info |

Examples

Hot-reload (edit api.json without restarting)

npx api-mock-core --watch

Custom port

npx api-mock-core --port 4000

Simulate slow network (Pro)

npx api-mock-core --delay 1500

Protect with API key (Pro)

npx api-mock-core --auth my-secret-key
# Client must send: X-API-Key: my-secret-key

Read-only mode (no writes)

npx api-mock-core --read-only

Share with team (Pro)

npx api-mock-core --share
# Prints a public HTTPS URL your whole team can use

Data Behaviour

• All data lives in memory — it resets when you restart the server
• POST auto-generates a UUID id if you don't provide one
• POST / PUT / PATCH automatically add createdAt and updatedAt timestamps
• PUT fully replaces the item (but preserves the original id)
• PATCH only updates the fields you send

Pro Features

| Feature | Free | Pro | |-----------------------|----------|----------| | All CRUD endpoints | ✅ | ✅ | | Filtering / sorting | ✅ | ✅ | | Pagination | ✅ | ✅ | | Hot-reload (--watch) | ✅ | ✅ | | API key auth | ✅ | ✅ | | Delay simulation | ≤ 500ms | Unlimited | | Team share (tunnel) | ❌ | ✅ | | Request validation | ❌ | ✅ | | Custom status code | ❌ | ✅ |

Contributing

1. Fork the repo
2. npm install
3. npm test
4. Open a PR

License

MIT © api-mock-core contributors