Hasan Ayvaz

Posted on Mar 6

mockapi-local: Get a Full REST API From a JSON Schema in One Command

#javascript #node #webdev #opensource

Every frontend developer knows the pain.

You're building a new feature. The backend isn't ready yet. So you either wait, write a bunch of hardcoded JSON files, or spin up a fake server that takes an hour to configure. Every time.

I got tired of this loop, so I built mockapi-local — a CLI tool that takes a JSON schema file and instantly gives you a fully working REST API with realistic fake data.

What It Does

You describe your data model in a schema.json file:

{
  "resources": {
    "users": {
      "count": 20,
      "fields": {
        "id": "uuid",
        "name": "fullName",
        "email": "email",
        "role": { "type": "enum", "values": ["admin", "user", "moderator"] },
        "createdAt": "pastDate"
      },
      "relations": {
        "posts": "posts"
      }
    },
    "posts": {
      "count": 50,
      "fields": {
        "id": "uuid",
        "title": "sentence",
        "body": "paragraph",
        "userId": { "type": "ref", "resource": "users" }
      }
    }
  },
  "config": {
    "delay": 200,
    "errorRate": 0.05
  }
}

Run one command:

mockapi-local serve schema.json --port 3000

And you instantly get:

GET    /users              → 20 fake users
POST   /users              → create a user
GET    /users/:id          → single user
PUT    /users/:id          → full update
PATCH  /users/:id          → partial update
DELETE /users/:id          → delete
GET    /users/:id/posts    → relational query
GET    /_spec              → OpenAPI 3.0 spec

No database. No config. No boilerplate.

It's Not Just for Simple Use Cases

I wanted something that could model real domains — not just the typical "users and posts" example. Here's a crypto exchange schema in action:

{
  "resources": {
    "coins": {
      "count": 20,
      "fields": {
        "id": "uuid",
        "symbol": { "type": "enum", "values": ["BTC", "ETH", "SOL", "ADA"] },
        "currentPrice": { "type": "number", "min": 1, "max": 65000 },
        "marketCap": { "type": "number", "min": 1000000, "max": 1200000000000 },
        "rank": { "type": "number", "min": 1, "max": 20 }
      }
    },
    "wallets": {
      "count": 30,
      "fields": {
        "id": "uuid",
        "userId": { "type": "ref", "resource": "users" },
        "coinId": { "type": "ref", "resource": "coins" },
        "balance": { "type": "number", "min": 0, "max": 10 }
      }
    }
  }
}

The ref field type ensures that every userId in wallets points to a real user ID — relational integrity out of the box.

Key Features

60+ field types powered by faker.js — uuid, email, fullName, pastDate, bitcoinAddress, iban, jwt, and many more. If a type isn't in the built-in list, it auto-resolves from faker.js modules. It will never throw an error on an unknown type.

Relational integrity — ref fields always reference real IDs from other resources. Resources are generated in dependency order automatically.

Full CRUD + query params — every resource gets pagination (?page=1&limit=10), filtering (?role=admin), and sorting (?sort=name&order=desc) built in.

OpenAPI 3.0 spec — hit GET /_spec and get a full auto-generated spec you can paste into Swagger UI or Postman.

Simulate real conditions — configure response delay and random error rate in the schema to test how your app handles slow or flaky APIs.

Graceful shutdown — single Ctrl+C stops the server cleanly.

vs json-server

The most common alternative is json-server, which is great. But it requires you to write the mock data yourself and doesn't generate it. mockapi-local takes the opposite approach — you define the shape, it handles the data.

Feature	mockapi-local	json-server
Data Generation	✅ Auto (Faker)	❌ Manual JSON
Schema-Driven	✅ Yes	❌ No
Relational Integrity	✅ Automatic	⚠️ Manual
OpenAPI Spec	✅ Auto-generated	❌ No
Latency Simulation	✅ Configurable	❌ No
Error Rate Simulation	✅ Configurable	❌ No
Graceful Shutdown	✅ Yes	❌ No

Getting Started

npm install -g mockapi-local

# Generate a sample schema
mockapi-local init

# Start the server
mockapi-local serve schema.json --port 3000

That's it. Your mock API is running at http://localhost:3000.

📦 npm: npmjs.com/package/mockapi-local
⭐ GitHub: github.com/Hasanayvzz/mockapi-local

If you find it useful, a star on GitHub goes a long way. And if you run into issues or have ideas for new field types or features, open an issue — contributions are very welcome. 🙌

DEV Community