⚡ mock-api-py (fastmock)

Modern Instant Mock CRUD Engine with FastAPI, Rich CLI, and Chaos Testing.
Spin up a full RESTful backend with filtering, sorting, pagination, and interactive Swagger documentation in under a second from a simple JSON file.

🚀 Why mock-api-py?

If you loved json-server, you will love mock-api-py even more:

• ⚡ Lightning Fast: Powered by ASGI and Uvicorn with async I/O.
• 📖 Interactive Swagger UI: Full OpenAPI docs automatically available at /docs and /redoc.
• 🎨 Modern Console UX: Styled Rich terminal output with detected resource tables and live-colored HTTP request logs.
• 🎲 Built-in Chaos Engine: Simulate realistic network conditions with latency jitter (--delay 200-800) and random 500 error injection (--error-rate 0.1) to test frontend resilience.
• 🔍 Advanced Query Engine:
  • Exact property filtering (category=electronics&inStock=true)
  • Comparative operators (price_gt=25, price_gte=50, price_lt=100, price_lte=100, price_ne=29.99)
  • Substring matching (title_like=mouse)
  • Full-text search across all object fields (q=wireless)
  • Multi-property sorting (_sort=price&_order=desc)
  • RFC-compliant pagination with X-Total-Count and Link headers (_page=1&_limit=10)
• 🔗 Nested Relational Routes: Automatically detects foreign keys (e.g. userId in products -> GET /users/1/products).
• 📘 Auto TypeScript Generator: One-click generation of fully-typed TypeScript interfaces for all collections (GET /_types and Studio viewer).
• 🔄 Instant Database Reset: Reset in-memory or persisted datasets back to initial boot state on-demand (POST /_reset or Studio button).
• 📤 Mock File Uploads: Upload images/documents via POST /upload with immediate static hosting at /uploads/<filename>.
• 🔌 Smart Auto-Port Fallback: Never crash due to a busy port; automatically finds and switches to the next free port.
• 🛡️ Mock Authentication Engine: Real HS256 JWT tokens, /auth/login, /auth/register, /auth/me, and bearer token protection on mutations (--auth).
• 🔀 Custom URL Rewriter: Map custom prefixes (/api/*), parameter aliases (/articles/:id), and query rewrites with routes.json (--routes).
• 💻 Embedded Web Studio Dashboard: Sleek dark-mode glassmorphic SPA at /_admin with live table/JSON views, search, query builder, TypeScript copy, and DB reset.
• 💾 Safe Atomic Persistence: In-memory speed by default with optional atomic write-back (--save) or strict --read-only mode.
• 👀 Live Watch Mode: Auto-reload in-memory data store when the JSON file changes on disk (--watch).
• 📁 Static File Serving: Serve static assets alongside mock APIs (--static ./public).

📦 Quickstart (Get Started in 5 Seconds)

You don't need to clone this repository, create virtual environments, or write a single line of code. Choose the method that best fits your workflow:

🌟 Method 1: Instant Zero-Install Run (Recommended via uvx)

If you have uv installed (the modern, ultra-fast Python package runner, equivalent to npx in Node.js):

Option A: Run immediately without any files

uvx mock-api-py

What happens: The server starts instantly with an in-memory starter database (posts, users, profile). No files are created on your disk!

Option B: Run with a JSON database file

uvx mock-api-py db.json

Magic Auto-Creation: If db.json does not exist in your folder yet, mock-api-py will automatically create a starter db.json with sample data for you on the spot, and start the server immediately!

🤖 Method 2: Generate Realistic Synthetic Data with Faker

Want custom test data (e.g. 20 users, 50 products, 30 posts)?

# Step 1: Generate realistic dataset
uvx mock-api-py generate --output db.json --schema "users:20,products:50,posts:30"

# Step 2: Boot the server
uvx mock-api-py db.json

🐍 Method 3: Classic Installation via pip

If you prefer installing tools permanently into your Python environment:

pip install mock-api-py

Then run with any of the available command aliases from anywhere:

mock-api db.json
# or
fastmock db.json
# or
mock-api-py db.json

🖥️ What to Expect When You Run It

Once started, your terminal displays an aesthetic dashboard showing your active endpoints:

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                     ⚡ mock-api v0.1.2 ⚡                         ┃
┃           Modern Instant Mock CRUD Server for Developers         ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 🚀 Server running at:      http://127.0.0.1:8000
 💻 Web Dashboard Studio:    http://127.0.0.1:8000/_admin
 📖 Interactive API Docs:     http://127.0.0.1:8000/docs
 📘 TypeScript Definitions:   http://127.0.0.1:8000/_types
 📤 File Upload Endpoint:     http://127.0.0.1:8000/upload
 ⏱️  Simulated Delay: 300ms | 💾 Auto-save: ON
 📦 Detected Resources:
   • GET /posts          [2 items]
   • GET /users          [1 item]
   • GET /profile        [1 object]

Now open your browser:

• Web Studio Dashboard: http://127.0.0.1:8000/_admin
• Interactive Swagger Docs: http://127.0.0.1:8000/docs
• API Endpoint: http://127.0.0.1:8000/posts

To stop the server at any time, simply press Ctrl + C in your terminal.

💡 Beginner FAQ & Troubleshooting

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

curl -LsSf https://astral.sh/uv/install.sh | sh

pip install uv

🛠️ CLI Usage & Flags

mock-api [DB_FILE] [OPTIONS]

Options

💻 Web Studio Dashboard (/_admin)

Access an interactive, modern dark-mode admin interface in your browser:

http://127.0.0.1:8000/_admin

Features:

• Live resource explorer showing all collections and singletons with real-time record counts.
• Instant full-text search (q=) and interactive sort controls.
• Single-click toggle between responsive data table and syntax-highlighted JSON viewer.
• 📘 TypeScript Modal: Preview and copy auto-generated TypeScript interfaces with a single click.
• 🔄 Reset DB Button: Revert the database back to its initial boot snapshot instantly.
• Direct links to Swagger OpenAPI documentation.

📘 TypeScript Types Generator (/_types)

Frontend developers can instantly generate strict TypeScript models matching their mock database:

# Fetch directly from CLI or build scripts
curl http://127.0.0.1:8000/_types > src/types/api.ts

Example generated output:

export interface User {
  id: number;
  name: string;
  email: string;
  role?: string;
}

export interface Product {
  id: number;
  title: string;
  price: number;
  category: string;
  inStock: boolean;
}

export interface Database {
  users: User[];
  products: Product[];
}

🔄 Instant Database Reset (/_reset)

Testing destructive flows like deleting items or wiping profiles? Reset the database to its exact server-boot state at any time:

curl -X POST http://127.0.0.1:8000/_reset

Or simply click the "🔄 Reset DB" button in the Web Studio (/_admin).

📤 Mock File Uploads (/upload)

Simulate avatar uploads, attachments, or image pickers without setting up S3 or local storage:

curl -F "file=@avatar.png" http://127.0.0.1:8000/upload

Response:

{
  "url": "/uploads/avatar.png",
  "filename": "avatar.png",
  "size": 42150,
  "contentType": "image/png"
}

The file is immediately accessible at http://127.0.0.1:8000/uploads/avatar.png.

🔌 Smart Auto-Port Fallback

Never get frustrated by Error: [Errno 48] Address already in use. If port 8000 is occupied by another app (or another mock-api instance), the engine smoothly seeks the next available port (8001, 8002, etc.) and starts right up with an alert in the console:

⚠️  Port 8000 is busy. Auto-switched to available port 8001.

🛡️ Mock Authentication & JWT

Simulate token-based authentication workflows in your frontend:

mock-api db.json --auth

When --auth is enabled:

1. Public endpoints: GET collection requests and Swagger docs remain accessible.
2. Mutating endpoints (POST, PUT, PATCH, DELETE) require an Authorization: Bearer <token> header, returning 401 Unauthorized if missing or invalid.
3. Authenticate and obtain tokens:
   • POST /auth/login with { "email": "alice@example.com", "password": "any" }
   • POST /auth/register with { "name": "Charlie", "email": "charlie@example.com" }
   • GET /auth/me with Authorization: Bearer <token>

🔀 Custom URL Rewriter

Rewrite API paths, map legacy endpoints, or add global prefixes using a routes.json file:

mock-api db.json --routes routes.json

routes.json:

{
  "/api/*": "/$1",
  "/articles/:id": "/posts/:id",
  "/top-products": "/products?_sort=price&_order=desc"
}

Now:

• GET /api/users ➔ routes to GET /users
• GET /articles/42 ➔ routes to GET /posts/42
• GET /top-products ➔ routes to GET /products?_sort=price&_order=desc

🎲 Chaos Engineering Examples

Test how your React, Vue, or mobile frontend handles flaky networks and server errors:

# Add fixed 500ms latency to every request
mock-api db.json --delay 500

# Simulate variable 3G mobile network (jitter between 200ms and 900ms)
mock-api db.json --delay 200-900

# Inject a 15% random failure rate to test Error Boundaries
mock-api db.json --error-rate 0.15

# Combine jitter, chaos errors, and auto-save
mock-api db.json --delay 100-400 --error-rate 0.1 --save

🤖 Synthetic Data Generation

Need test data immediately? Generate realistic datasets with Faker:

mock-api generate --output data.json --schema "users:20,products:50,posts:30,comments:100"

Then boot it right up:

mock-api data.json

Supported built-in schemas: users, products, posts, comments, todos, companies, plus generic custom names.

📡 REST API & Query Reference

Standard CRUD Endpoints

• GET /products - List products with query filtering
• GET /products/1 - Get product by ID
• POST /products - Create product (auto-generates unique ID)
• PUT /products/1 - Replace product
• PATCH /products/1 - Partially update product
• DELETE /products/1 - Delete product

Singleton Endpoints

• GET /profile - Get singleton object
• PATCH /profile - Update singleton fields

Query Parameters

For detailed documentation, see docs/api.md.

🧪 Running Tests

# Create virtualenv and install dependencies
uv venv
uv pip install -e ".[dev]"

# Run full test suite
uv run pytest -v

📄 License

MIT © Alexandr Motologa