api-mock-cli/README.md

API Mock CLI

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

1. Initialize a new mock project:

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

2. Start the mock server:

api-mock start

3. 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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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