tkb_timeshift/claude_n8n/tools/mock_api_server/README.md

Mock API Server for N8N Testing

A Docker-containerized REST API server that serves test data from JSON files for N8N workflow development and testing.

Overview

This mock API server provides a consistent, controllable data source for testing N8N workflows without relying on external APIs. It serves data from JSON files and includes features like pagination, random data selection, and file upload capabilities.

Files Structure

mock_api_server/
├── README.md              # This documentation
├── Dockerfile             # Docker image definition
├── docker-compose.yml     # Docker Compose configuration
├── mock_api_server.py     # Main Python Flask server (symlinked from ../mock_api_server.py)
└── api_data/              # JSON data files directory
    ├── matrix_messages.json   # Matrix chat messages sample data
    └── test_data.json         # Simple test data

Quick Start

Using Docker Compose (Recommended)

cd /home/klas/claude_n8n/tools/mock_api_server
docker compose up -d

The server will be available at: http://localhost:5002

Using Docker Build

cd /home/klas/claude_n8n/tools/mock_api_server
docker build -t mock-api-server .
docker run -d -p 5002:5000 -v $(pwd)/api_data:/app/api_data mock-api-server

Using Python Directly

cd /home/klas/claude_n8n/tools
python mock_api_server.py --host 0.0.0.0 --port 5002 --data-dir mock_api_server/api_data

API Endpoints

Health Check

• GET /health - Server status and available endpoints

Data Access

• GET /data - List all available data files
• GET /data/<filename> - Get data from specific file (.json extension optional)
• GET /random/<filename> - Get random item from array data
• GET /paginated/<filename>?page=1&per_page=10 - Get paginated data

Special Endpoints

• GET /matrix - Alias for /data/matrix_messages.json
• POST /upload?filename=<name> - Upload new JSON data file

Query Parameters

• page - Page number for pagination (default: 1)
• per_page - Items per page (default: 10)
• filename - Target filename for upload (without .json extension)

Example Usage

Health Check

curl http://localhost:5002/health

Get Test Data

curl http://localhost:5002/data/test_data.json
# Returns: {"message": "Hello from mock API", "timestamp": 1234567890, "items": [...]}

Get Random Item

curl http://localhost:5002/random/test_data
# Returns random item from the test_data.json array

Paginated Data

curl "http://localhost:5002/paginated/matrix_messages?page=1&per_page=5"

Upload New Data

curl -X POST "http://localhost:5002/upload?filename=my_data" \
  -H "Content-Type: application/json" \
  -d '{"test": "value", "items": [1,2,3]}'

Data Files

Adding New Data Files

1. Via File System: Add .json files to the api_data/ directory
2. Via API: Use the /upload endpoint to create new files
3. Via Container: Mount additional volumes or copy files into running container

Data File Format

Files should contain valid JSON. The server supports:

• Objects: {"key": "value", "items": [...]}
• Arrays: [{"id": 1}, {"id": 2}]

Sample Data Files

test_data.json

{
  "message": "Hello from mock API",
  "timestamp": 1234567890,
  "items": [
    {"id": 1, "name": "Item 1"},
    {"id": 2, "name": "Item 2"},
    {"id": 3, "name": "Item 3"}
  ]
}

matrix_messages.json

Contains sample Matrix chat room messages with realistic structure for testing chat integrations.

Configuration

Environment Variables

• PYTHONUNBUFFERED=1 - Enable real-time Python output in Docker

Docker Compose Configuration

• Host Port: 5002
• Container Port: 5000
• Volume Mount: ./api_data:/app/api_data
• Restart Policy: unless-stopped

Health Check

Docker includes automatic health checking via curl to /health endpoint.

Integration with N8N

HTTP Request Node Configuration

Method: GET
URL: http://host.docker.internal:5002/data/test_data

Webhook Testing

Use the mock API to provide consistent test data for webhook development and testing.

Data Processing Workflows

Test data transformation nodes with predictable input from the mock API.

Development

Adding New Endpoints

Edit mock_api_server.py and add new Flask routes. The server will automatically restart in development mode.

Debugging

Check container logs:

docker compose logs -f mock-api

Stopping the Server

docker compose down

Troubleshooting

Port Already in Use

If port 5002 is occupied, edit docker-compose.yml and change the host port:

ports:
  - "5003:5000"  # Change 5002 to 5003

File Permissions

Ensure the api_data directory is writable for file uploads:

chmod 755 api_data/

Container Not Starting

Check if all required files are present:

ls -la mock_api_server.py Dockerfile docker-compose.yml api_data/

Related Files

• Main Server Script: /home/klas/claude_n8n/tools/mock_api_server.py
• N8N Tools Directory: /home/klas/claude_n8n/tools/
• Original Development Files: /home/klas/mem0/.claude/ (can be removed after migration)