simple-api-mock-server 0.3.1

A simple, file-based API mocking server.

Simple API Mock Server

A simple, file-based API mocking server built with Flask, designed to help developers quickly simulate API endpoints for testing and development.

🔧 Features

Core Functionality

• Dynamic Routing: Define API endpoints from a api.json or api.yaml file.
• OpenAPI Specification: Automatically generates a rich OpenAPI v3 specification at /openapi.json.
• Metrics Endpoint: Exposes Prometheus-style metrics at /metrics.
• Graceful 404 Handling: Custom JSON 404 responses for unknown routes.
• CORS Support: Integrated Flask-Cors to handle Cross-Origin Resource Sharing.

Configuration & Customization

• YAML Configuration: Supports .yml and .yaml configuration files.
• Templating for Request Body Parameters: Responses can be dynamically templated using values from the request body.
• Custom Response Headers per Method: Define specific HTTP headers for different methods within the same route.
• Descriptions and Metadata: Add optional description and tags fields to your API endpoints for better documentation and categorization.
• Example Request Bodies: Include optional request_body fields in api.json for documenting expected request payloads.
• Static File Serving: Serve static files (e.g., UI assets) from a specified folder via a CLI argument.

Authentication & Security

• Improved Authentication Logic: Refactored for clarity, consistency, and maintainability.
• Granular Rate Limiting: Rate limiting can now be applied per client IP or API key for more realistic throttling. Old rate limit entries are pruned to prevent memory growth.
• API Key in Query Params: API keys can be sent via query parameters (?api_key=...) as well as headers.
• Auth Challenge Headers: 401 Unauthorized responses for Basic and Bearer auth now include WWW-Authenticate headers.

Development & Operations

• Enhanced Metrics Tracking: Thread-safe and semantically clearer metrics using collections.Counter.
• Robust Error Handling: Improved error logging with logger.exception() and user-friendly messages for port binding errors and malformed JSON.
• Thread-Safe Rate Limiting: Implemented threading.Lock to prevent race conditions in rate limiting.
• Hot Reloading: Automatically restarts the server when api.json changes (requires --debug flag).
• Graceful Shutdown: Handles SIGINT, SIGTERM, and KeyboardInterrupt for clean server termination.
• Comprehensive Logging: Detailed logging for server operations, requests, and errors.
• Modular Configuration: Separated configuration validation and loading logic into a dedicated module.

Installation

From PyPI (Recommended, once published)

pip install simple-api-mock-server

From Source

1. Clone the repository:

   </code></pre>
   </li>
   </ol>
   <p>git clone <a href="https://github.com/sanatladkat/simple-api-mock-server.git">https://github.com/sanatladkat/simple-api-mock-server.git</a>
   cd simple-api-mock-server
   ```</p>
   <ol start="2">
   <li>
   <p><strong>Create a virtual environment:</strong></p>
   <pre><code class="language-bash">
   

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ```

3. Install dependencies:

   </code></pre>
   </li>
   </ol>
   <p>pip install -r requirements.txt
   pip install -e .
   ```</p>
   <h2><a href="#user-content--quick-start" aria-hidden="true" class="anchor" id="user-content--quick-start"></a>🚀 Quick Start</h2>
   <p>To get a mock server up and running quickly:</p>
   <ol>
   <li>
   <p><strong>Create a file <code>api.json</code> or <code>api.yaml</code></strong> with the following content:</p>
   <pre><code class="language-yaml">
   

• path: /hello methods:
  • GET response: data: message: "Hello, world!" code: 200

2. Run the server from your project root:

   </code></pre>
   </li>
   </ol>
   <p>simple-mock-server --config api.yaml
   ```</p>
   <ol start="3">
   <li><strong>Visit:</strong> <code>http://localhost:5001/hello</code> in your browser or API client.</li>
   </ol>
   <h2><a href="#user-content--pypi-package" aria-hidden="true" class="anchor" id="user-content--pypi-package"></a>📦 PyPI Package</h2>
   <p>You can install via pip:</p>
   <pre><code class="language-bash">pip install simple-api-mock-server
   

   📄 View on PyPI # Placeholder: Update with actual PyPI link after publishing

   Usage

   1. Create an api.json or api.yaml file:

      This file defines your API endpoints and their responses. See the Configuration section for details and examples.

   2. Run the server:

      </code></pre>
      </li>
      </ol>
      <p>simple-mock-server --config api.json --port 5001 --debug --verbose --static-folder ./static
      ```</p>
      <pre><code>**CLI Options:**
      *   `--config <path>`: Path to the API configuration file (JSON or YAML). (default: `api.json`).
      *   `--port <number>`: Port to run the server on (default: `5001`).
      *   `--host <address>`: Host to bind the server to (default: `127.0.0.1`).
      *   `--debug`: Enable Flask debug mode and hot reloading (auto-reloader for code changes).
      *   `--verbose`: Enable verbose logging.
      *   `--static-folder <path>`: Path to a static folder to serve files from (e.g., for UI assets). Static files will be served at `/static/<filename>`.
      

      3. Access the mock API:

         The server will be running at http://127.0.0.1:5001 (or your specified port).

      ⚠️ Security Note

      This mock server is intended for development and testing purposes only. It should not be exposed to the public internet or used in production environments, as it lacks proper authentication, authorization, and input validation safeguards beyond simulation.

      🛠️ Configuration Reference

      The configuration file (JSON or YAML) is a list of route objects. Each route object can have the following properties:

      • path (string, required): The URL path for the endpoint (e.g., /users, /users/{user_id}). Flask's route variable syntax is supported.
      • methods (array of strings, required): A list of HTTP methods this endpoint responds to (e.g., ["GET", "POST"]).
      • response (object, required): An object defining the response to return.
        • data (object or array, required): The JSON content to return as the response body.
          • Dynamic Responses:
            • Route Variables: Use {variable_name} in the response JSON to inject values from route variables (e.g., "id": "{user_id}").
            • Query Parameters: Use {query_param:param_name} to inject values from URL query parameters (e.g., "message": "Hello, {query_param:name}!").
            • Request Body Parameters: Use {body_param:param_name} to inject values from the JSON request body (e.g., "received_name": "{body_param:name}").
          • Echo Request Body: Include "echo": true in the data object to have the server return the same JSON request body it received (instead of the static data response). Useful for testing POST/PUT payloads.
        • code (integer, optional): The HTTP status code to return (default: 200). For 204 No Content responses, the body will be empty.
        • delay (number, optional): The delay in seconds before sending the response, simulating network latency (default: 0).
        • headers (object, optional): A dictionary of custom HTTP headers to include in the response (e.g., "X-Custom-Header": "MyValue"). Headers can also be templated.
      • description (string, optional): A brief description of the endpoint's purpose.
      • tags (array of strings, optional): A list of tags for categorizing the endpoint.
      • auth (object, optional): Configuration for authentication simulation.
        • api_key (string, required if auth is present): The expected API key. The server will look for this in the X-API-Key header or api_key query parameter. If it doesn't match, a 401 Unauthorized response is returned.
        • basic_auth (object, optional): Basic authentication credentials (username, password). If authentication fails, a 401 Unauthorized response with a WWW-Authenticate: Basic realm="Authentication Required" header is returned.
        • bearer_token (string, optional): Bearer token. If authentication fails, a 401 Unauthorized response with a WWW-Authenticate: Bearer realm="Authentication Required" header is returned.
        • skip_auth (boolean, optional): Set to true to disable authentication for this endpoint.
      • rate_limit (object, optional): Configuration for rate limiting.
        • requests (integer, required): Maximum number of requests allowed.
        • window (integer, required): Time window in seconds for the rate limit.
        • Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After) are automatically included in responses. Rate limiting is applied per client IP or API key.
      • request_body (object, optional): An example or schema for the expected request body (for documentation/validation).
      • query_params (array of objects, optional): A list of query parameters for the endpoint.
        • name (string, required): The name of the query parameter.
        • required (boolean, optional): Whether the query parameter is required (default: false).
        • type (string, optional): The type of the query parameter (default: string).

      api.yaml Example

      - path: /
        methods:
          - GET
        description: Welcome endpoint
        tags:
          - General
        response:
          data:
            message: Welcome to the mock server!
          code: 200
      
      - path: /api/users
        methods:
          - GET
        description: Get all users
        tags:
          - Users
        response:
          data:
            - id: 1
              name: John Doe
            - id: 2
              name: Jane Doe
          code: 200
      
      - path: /api/users
        methods:
          - POST
        description: Create a new user
        tags:
          - Users
        request_body:
          name: string
          email: string
        response:
          data:
            message: User {body_param:name} created successfully
          code: 201
      
      - path: /api/users/{user_id}
        methods:
          - GET
        description: Get user by ID
        tags:
          - Users
        response:
          data:
            id: "{user_id}"
            name: "User {user_id}"
          headers:
            X-User-Id: "{user_id}"
          code: 200
      
      - path: /api/greet
        methods:
          - GET
        description: Greet a user by name from query param
        tags:
          - Utilities
        query_params:
          - name: name
            required: true
            type: string
        response:
          data:
            message: "Hello, {query_param:name}!"
          code: 200
      
      - path: /api/protected
        methods:
          - GET
        description: Protected endpoint with API key authentication
        tags:
          - Authentication
        response:
          data:
            message: Access granted!
          code: 200
        auth:
          api_key: my-secret-api-key
      
      - path: /api/rate-limited
        methods:
          - GET
        description: Endpoint with rate limiting enabled (2 requests per 60 seconds)
        tags:
          - Rate Limiting
        response:
          data:
            message: You are not rate limited yet!
          code: 200
        rate_limit:
          requests: 2
          window: 60
      

      For a more comprehensive example, refer to the api.json example below.

      Testing

      To run the unit and integration tests, navigate to the project root and execute:

      pip install ".[dev]" # Install development dependencies (requests, pytest) for running tests and contributing to development.
      pytest
      

      ❗ Troubleshooting

      Versioning and Changelog

      See the CHANGELOG.md for details on releases and changes.

      License

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