mock-me — Instant FastAPI Mock Servers

// workflow

Three steps to a mock backend

From zero to a fully running API server with Swagger UI in under a minute.

📄

Write a JSON config

Define endpoints, response schemas, HTTP methods, delays, and error cases. No Python required — just JSON.

// config.json

⚡

Run one command

mock-me parses your config, registers all routes, and boots a live FastAPI server with hot-reload.

$ mock-me start config.json

🌐

Hit real endpoints

Your frontend calls real HTTP endpoints. Realistic fake data, pagination, and Swagger UI are all ready instantly.

→ localhost:8000/docs

// capabilities

Everything a frontend dev needs

Built for the gap between design mockups and a real backend.

🧠

Schema-aware data engine

Strings become names, emails, sentences. Numbers get ranges. Dates are realistic timestamps. Arrays have configurable lengths. All driven by Faker.

40+ faker types

🔀

Conditional responses

Return different status codes and bodies based on path params, query strings, request body fields, or headers. First match wins.

path · query · body · header

💥

Error simulation

Inject failures by probability (5% 503s) or by condition (locked@example.com → 403). Test your error handling before the real backend exists.

probability · trigger

📋

Pagination built-in

Set paginated: true on any endpoint. Automatic page/size/total/hasNext envelope. Configurable field names and max page sizes.

auto-wrapping

⏱

Latency simulation

Global, per-endpoint, or per-response delays. Simulate real-world network conditions during frontend development without a real backend.

global · endpoint · response

🌱

Seeded randomness

Set a seed for fully reproducible fake data across runs. Perfect for snapshot testing — same config, same seed, same data every time.

reproducible

🔌

Plugin system

Register custom Python data generators in a plugin file. Expose a GENERATORS dict and reference your types directly in the config JSON.

extensible

🔄

Hot-reload

Run with --reload and the file watcher detects config changes. Routes update without restarting the server manually.

watch mode

📦

Export standalone server

Generate a zero-dependency server.py that only needs fastapi + uvicorn + faker. Share it without mock-me installed.

mock-me export

// config schema

One JSON file, infinite APIs

Intuitive, human-readable config. No boilerplate, no code — just describe what you want.

              {
              "path":
              "/api/users/{userId}",
              "method": "GET",
              "description":
              "Get user by ID",
              "tags": ["Users"],
              "delay": 0.2,
              // 200ms latency

              "pathParams": {
              "userId": {
              "type": "string",
              "required": true
              } },

              "queryParams": {
              "include": {
              "type": "string"
              } },

              "conditionalResponses":
              [
              {
              "when": {
              "path.userId":
              "000" },
              "response": {
              "status": 404,
              "body": {
              "error": {
              "type": "string",
              "value":
              "Not found" }
              }
              }
              }
              ],

              "response": {
              "status": 200,
              "body": {
              "id": {
              "type": "string",
              "template":
              "{{userId}}" },
              "email": {
              "type": "string",
              "faker": "email"
              }, "name":
              { "type":
              "string", "faker":
              "name" }
              }
              }
              }
            

              "body": {
              // UUID field
              "id": {
              "type": "uuid"
              },

              // Faker string shorthand
              "email": {
              "type": "string",
              "faker": "email"
              },

              // Number with range
              "price": {
              "type": "float",
              "min": 0.99,
              "max": 999.99
              },

              // Enum – picks one randomly
              "status": {
              "type": "enum",
              "values": ["active","inactive"] },

              // Template – echoes request param
              "orderId": {
              "type": "string",
              "template":
              "ORD-{{int}}" },

              // Nullable – 10% chance of null
              "deletedAt":{
              "type": "date",
              "nullable": true
              },

              // Nested object
              "address": {
              "type": "object",
              "properties": {
              "city": {
              "type": "string",
              "faker": "city"
              }, "country":
              { "type":
              "string", "faker":
              "country" }
              }
              },

              // Array of objects
              "tags": {
              "type": "array",
              "minItems": 1,
              "maxItems": 5,
              "items": {
              "type": "string",
              "faker": "word"
              }
              }
              }
            

              // Conditions use dotted key paths:
              // path.{param} query.{param}
              // body.{field} header.{name}
              // Use "*" to check presence (any value)

              "conditionalResponses":
              [
              {
              "when": {
              "path.id": "000"
              }, "response":
              { "status":
              404 }
              },
              {
              "when": {
              "query.role":
              "admin" },
              "response": {
              "status": 200,
              "body": { ...
              } }
              }
              ],

              // Error simulation:
              "errors": [
              {
              "probability":
              0.05,
              // 5% random failure
              "response": {
              "status": 503
              } },
              {
              "trigger": {
              "body.email":
              "locked@example.com"
              }, "response":
              { "status":
              403 }
              }
              ]
            

Template strings

Echo request values back into responses using {{variable}} syntax. Resolves path params, query params, body fields, or any Faker method.

"template": "ORD-{{int}}" → "ORD-4291"
"template": "{{userId}}" → "abc123"

Pagination envelope

Set "paginated": true on any GET endpoint. Responses are automatically wrapped with page, size, total, hasNext, and hasPrev fields.

"paginated": true → {items, total, page, pages, hasNext}

Global config

Set global headers, delays, seed, and environment at the top level. Endpoint-level settings override globals.

"seed": 42 — reproducible data every run
"globalDelay": 0.05 — 50ms on all routes

Plugin system

Drop a Python file with a GENERATORS dict. Register custom types like "product_sku" or "geo_point" and use them in any schema.

"plugins": ["./my_plugin.py"]
{ "type": "product_sku" }

// sample config

14-endpoint e-commerce API

Included sample_config.json gives you a full e-commerce backend in one file.

GET/api/v1/usersList users — paginated, filterableUsers

GET/api/v1/users/{userId}Get user by ID — conditional 404 on "000"Users

POST/api/v1/usersCreate user — conflict on taken emailUsers

PATCH/api/v1/users/{userId}Update user profile fieldsUsers

POST/api/v1/auth/loginLogin — 401/403 for wrong/locked accountsAuth

GET/api/v1/productsList products — paginated, nested schemasProducts

GET/api/v1/products/{id}Product detail with reviews arrayProducts

GET/api/v1/ordersList orders with date filteringOrders

POST/api/v1/ordersPlace order — 5% random 503 errorOrders

DELETE/api/v1/orders/{orderId}Cancel order — 422 if already shippedOrders

GET/api/v1/searchFull-text search — 400 on empty querySearch

GET/api/v1/analytics/dashboardAdmin metrics — 401 without API keyAnalytics

GET/api/v1/notificationsUser notification feedNotifs

POST/api/v1/uploadFile upload — 3% random 413 errorUploads

// cli reference

Four commands. Full control.

Everything runs through the mock-me CLI — or prefixed with pdm run.

▶

start — run the mock server

Boot the server. Console shows routes, timestamps, and response codes in real time.

$ mock-me start config.json

$ mock-me start config.json --port 9000

$ mock-me start config.json --reload --seed 42

✓

validate — check your config

Parse and validate a config file without starting the server. Lists all registered endpoints.

$ mock-me validate config.json

↗

export — standalone server.py

Generate a self-contained FastAPI file requiring only fastapi, uvicorn, and faker. No mock-me dependency.

$ mock-me export config.json

$ mock-me export config.json --out api.py

init — scaffold a config

Write a starter config.json to disk based on the sample e-commerce template.

$ mock-me init

$ mock-me init --out my_api.json

// data engine

40+ realistic fake data types

Every type generates contextually appropriate values. Just set "faker": "type_name" on any string field.

nameJonathan Johnson

first_nameSofia

last_nameOkafor

emailuser@example.com

usernamejohn21

password*P@ssw0rd!*

phone+1 (415) 555-0192

companyAcme Corp Ltd

jobSenior Engineer

address123 Main St, SF

street742 Evergreen Ter

citySan Francisco

stateCalifornia

countryUnited States

zip94102

urlhttps://example.com

domainacme.io

ipv4192.168.1.42

ipv62001:db8::1

mac00:1A:2B:3C:4D:5E

uuida3f8c2d1-...

wordinstitution

sentenceWorld talk herself law.

paragraphRange successful...

slugworld-talk-herself

colorMediumOrchid

hex_color#a3d48f

currencyUSD

image_urlpicsum.photos/...

ibanGB29 NWBK ...

ssn078-05-1120

user_agentMozilla/5.0...

mime_typeimage/jpeg

file_namereport_q3.pdf

license_plateXY-4829-Z

// extensibility

Need a custom type? Write a plugin.

Drop a Python file with a GENERATORS dict. Reference it in your config's "plugins" array. Your custom type names become first-class field types.

Expose GENERATORS in your plugin file — a dict mapping type names to callables.

Reference

Use "plugins": ["./my_plugin.py"] in the top-level config, then "type": "product_sku" in any body field.

No restart needed

Plugins are loaded at startup. Use --reload to pick up plugin + config changes together.

            # my_plugin.py
            import
            random

            def
            _product_sku():
            return
            f"SKU-{random.randint(10000,99999)}"

            def
            _geo_point():
            return {
            "lat":
            round(random.uniform(-90,
            90),
            6),
            "lng":
            round(random.uniform(-180,
            180),
            6), }

            def
            _semver():
            return
            f"{random.randint(0,9)}.{random.randint(0,20)}.{random.randint(0,100)}"

            # Required export
            GENERATORS = {
            "product_sku":
            _product_sku, "geo_point":
            _geo_point, "semver":
            _semver, }

            # In config.json:
            { "type": "product_sku" } → "SKU-47291"
            { "type": "geo_point" } → {"lat":37.4,"lng":-122.1}
            { "type": "semver" } → "2.14.3"
          

Instant
mock servers.
Zero code.

Three steps to a mock backend

Write a JSON config

Run one command

Hit real endpoints

Everything a frontend dev needs

Schema-aware data engine

Conditional responses

Error simulation

Pagination built-in

Latency simulation

Seeded randomness

Plugin system

Hot-reload

Export standalone server

One JSON file, infinite APIs

14-endpoint e-commerce API

Four commands. Full control.

40+ realistic fake data types

Need a custom type? Write a plugin.

Your mock backend,
running in seconds

Instant mock servers. Zero code.

Three steps to a mock backend

Write a JSON config

Run one command

Hit real endpoints

Everything a frontend dev needs

Schema-aware data engine

Conditional responses

Error simulation

Pagination built-in

Latency simulation

Seeded randomness

Plugin system

Hot-reload

Export standalone server

One JSON file, infinite APIs

14-endpoint e-commerce API

Four commands. Full control.

40+ realistic fake data types

Need a custom type? Write a plugin.

Your mock backend,running in seconds

Instant
mock servers.
Zero code.

Your mock backend,
running in seconds