mock-api-cli

Spin up a mock REST API server from a JSON schema file in seconds. No dependencies. Pure Node.js.

Features

• Zero dependencies — uses only Node.js built-ins (http, fs, path, url)
• Define any GET / POST / PUT / PATCH / DELETE routes in a single JSON file
• Auto-generates a sample routes.json on first run
• Path parameters (:id, :slug) matched automatically
• Wildcard paths (/files/*)
• CORS headers included by default
• Simulated network delay (--delay)
• Verbose request logging (--verbose)

Install

npm install -g mock-api-cli

Or use without installing:

npx mock-api-cli --port 3001

Quick Start

# Start on default port 3000 (auto-creates routes.json)
mock-api

# Start on custom port with custom config
mock-api --port 8080 --config my-api.json

# Add 200ms artificial latency
mock-api --port 3001 --delay 200

# Log every request
mock-api --verbose

Config Format (routes.json)

[
  {
    "method": "GET",
    "path": "/users",
    "status": 200,
    "response": [
      { "id": 1, "name": "Alice", "email": "[email protected]" },
      { "id": 2, "name": "Bob",   "email": "[email protected]" }
    ]
  },
  {
    "method": "GET",
    "path": "/users/:id",
    "status": 200,
    "response": { "id": 1, "name": "Alice", "email": "[email protected]" }
  },
  {
    "method": "POST",
    "path": "/users",
    "status": 201,
    "response": { "id": 3, "created": true }
  },
  {
    "method": "DELETE",
    "path": "/users/:id",
    "status": 200,
    "response": { "deleted": true }
  },
  {
    "method": "GET",
    "path": "/health",
    "status": 200,
    "response": { "status": "ok" }
  }
]

Each route object has:

| Field | Type | Description | |------------|-----------------|------------------------------------------| | method | string | HTTP method (GET, POST, PUT, PATCH, DELETE) | | path | string | URL path — supports :param and /* wildcards | | status | number | HTTP response status code (default: 200) | | response | object or array | JSON body to return |

CLI Options

--port,    -p  <number>   Port to listen on            (default: 3000)
--config,  -c  <file>     Path to routes JSON file     (default: routes.json)
--delay,   -d  <ms>       Artificial response delay
--verbose                 Log every incoming request
--version, -v             Show version
--help,    -h             Show help

Example Session

$ mock-api --port 3001
[mock-api] Server running at http://localhost:3001
[mock-api] Loaded 7 route(s):

  GET     /users         → 200
  GET     /users/:id     → 200
  POST    /users         → 201
  PUT     /users/:id     → 200
  DELETE  /users/:id     → 200
  GET     /products      → 200
  GET     /health        → 200

$ curl http://localhost:3001/users
[
  { "id": 1, "name": "Alice Johnson", ... },
  ...
]

$ curl http://localhost:3001/users/42
{ "id": 1, "name": "Alice Johnson", ... }

$ curl -X POST http://localhost:3001/users
{ "id": 4, "created": true }

$ curl http://localhost:3001/nonexistent
{ "error": "Not Found", "message": "No route matched: GET /nonexistent", ... }

Use Cases

• Frontend development without a real backend
• Testing API client code
• CI/CD pipeline integration tests
• Teaching REST API concepts
• Prototyping new services

License

MIT