A powerful CLI tool that converts API definitions into shareable local mock servers. Developers provide endpoint definitions with response templates, and the tool automatically generates a fully functional mock server with intelligent routing, request validation, and dynamic response templating.

Features

Automatic Mock Server: Spin up a FastAPI-based mock server from YAML/JSON endpoint definitions
Smart Endpoint Routing: Pattern matching for endpoints including path parameters and HTTP methods
Shareable Local URLs: Expose your local server via ngrok tunneling for team collaboration
Request Validation: Validate incoming requests against JSON schemas
Dynamic Response Templating: Generate responses using Jinja2 variable substitution
Offline Mode: Run without external dependencies for testing environments

Quick Start

Installation

pip install api-mock-cli

Or from source:

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/api-mock-cli.git
cd api-mock-cli
pip install -e .

Basic Usage

Initialize a new mock project:

api-mock init --name my-api
cd my-api

Start the mock server:

api-mock start

Test your endpoints:

curl http://localhost:8000/api/hello

Commands

init

Create a new mock project structure with predefined templates.

api-mock init --name my-api [--template basic|full|minimal]

Options:

--name (required): Name of the mock project
--template: Project template (default: basic)
- basic: Simple single-endpoint setup
- full: Multi-endpoint with validation examples
- minimal: Bare-bones structure

start

Start the mock server with optional configuration.

api-mock start [--port 8000] [--host 0.0.0.0] [--offline] [--reload]

Options:

--port: Server port (default: 8000)
--host: Server host (default: 0.0.0.0)
--offline: Disable ngrok tunneling
--reload: Enable auto-reload on file changes

stop

Stop the running mock server.

api-mock stop

generate

Generate a new endpoint definition file.

api-mock generate EndpointName --method GET --path /api/endpoint

Options:

EndpointName (required): Name for the new endpoint
--method: HTTP method (GET, POST, PUT, DELETE, PATCH)
--path: URL path for the endpoint

Configuration

Create a config.yaml file in your project root:

name: my-mock-api
version: 1.0.0
server:
  port: 8000
  host: 0.0.0.0
  tunnel: true
  offline: false
  reload: true
  log_level: info

Environment Variables

Variable	Description	Default
`API_MOCK_PORT`	Server port	8000
`API_MOCK_HOST`	Server host	0.0.0.0
`API_MOCK_OFFLINE`	Run without tunneling	false
`NGROK_AUTHTOKEN`	ngrok authentication token	-
`API_MOCK_LOG_LEVEL`	Logging level	info

Endpoint Definition

Define endpoints in endpoints.yaml:

version: "1.0.0"
endpoints:
  - path: /api/users/{id}
    method: GET
    name: Get User
    description: Retrieve a user by ID
    response:
      status_code: 200
      body:
        id: "{{request.path.id}}"
        name: "John Doe"
        email: "john@example.com"
    validators:
      body:
        type: object
        required: [name, email]
        properties:
          name: {type: string, minLength: 1}
          email: {type: string, format: email}

Response Templating

Use Jinja2 templates for dynamic responses:

Template	Description
`{{request.path.id}}`	Path parameters
`{{request.query.page}}`	Query parameters
`{{request.body.name}}`	Request body fields
`{{request.headers.Authorization}}`	Request headers
`{{uuid}}`	Generate UUID v4
`{{timestamp}}`	Current ISO timestamp
`{{random_int(1, 100)}}`	Random integer in range
`{{random_choice}}`	Random item from list

Response Headers

response:
  status_code: 201
  headers:
    Content-Type: application/json
    X-Request-Id: "{{uuid}}"
  body:
    success: true

Status Codes

response:
  status_code: 404
  body:
    error: "Resource not found"

Project Structure

my-api/
├── config.yaml
├── endpoints.yaml
├── responses/
│   └── user.json
├── schemas/
│   └── user.json
└── README.md

Offline Mode

Run the mock server without ngrok tunnel for internal networks or testing:

api-mock start --offline

Installation for Development

git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/api-mock-cli.git
cd api-mock-cli

python -m venv venv
source venv/bin/activate

pip install -e ".[dev]"

pytest tests/ -v
ruff check .

Tech Stack

FastAPI: Web framework for building APIs
Click: CLI framework
Uvicorn: ASGI server
Pydantic: Data validation
PyNgrok: ngrok integration for tunneling
Jinja2: Template engine
PyYAML: YAML parsing

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

v0.1.0 (2024-01-29)

Initial release
Basic mock server functionality
Endpoint routing with path parameters
Request validation support
Response templating with Jinja2
ngrok tunnel integration
CLI commands: init, start, stop, generate