AI API Gateway Local Development

Prerequisites & Setup

Before setting up a local AI API gateway, ensure you have the necessary tools and configurations:

Required Software

• Docker Desktop
• Node.js 18+ or Python 3.9+
• Git
• API keys from providers

Recommended Tools

• Postman or Insomnia
• VS Code with extensions
• jq for JSON processing
• httpie for CLI testing

System Requirements

• 8GB RAM minimum
• 20GB disk space
• macOS, Linux, or WSL2
• Port 8080 available

Docker Configuration

The recommended approach for local development is using Docker containers for consistent environments:

Docker Compose Setup

version: '3.8'

services:
  api-gateway:
    image: ai-api-gateway:latest
    ports:
      - "8080:8080"
      - "9090:9090"
    environment:
      - GATEWAY_MODE=development
      - LOG_LEVEL=debug
      - CACHE_ENABLED=true
    volumes:
      - ./config:/etc/gateway/config
      - ./logs:/var/log/gateway
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data

volumes:
  redis-data:

Environment Variables

Create a .env file in your project root:

# API Provider Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_AI_API_KEY=...

# Gateway Configuration
GATEWAY_PORT=8080
ADMIN_PORT=9090
LOG_LEVEL=debug
RATE_LIMIT_ENABLED=true

# Cache Configuration
REDIS_URL=redis://redis:6379
CACHE_TTL=3600

# Development Settings
CORS_ENABLED=true
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

Security Note Never commit your .env file to version control. Add it to .gitignore and use environment variable injection in CI/CD pipelines.

Quick Start Commands

Essential commands for local development:

Starting the Gateway

# Start all services docker-compose up -d # View logs in real-time docker-compose logs -f api-gateway # Check service health curl http://localhost:8080/health/live

Configuration Management

# Hot reload configuration (if supported) docker-compose restart api-gateway # Rebuild after code changes docker-compose up -d --build # Stop all services docker-compose down # Clean up volumes docker-compose down -v

Testing Commands

# Test basic completion curl -X POST http://localhost:8080/v1/completions \ -H "Authorization: Bearer dev-key" \ -H "Content-Type: application/json" \ -d '{"model": "gpt-3.5-turbo", "prompt": "Hello, world!"}' # Check available models curl http://localhost:8080/v1/models

Testing Strategies

Comprehensive testing approach for local development:

Test Type	Purpose	Tool
Unit Tests	Test individual components and functions	pytest / Jest
Integration Tests	Test component interactions	pytest / Supertest
API Contract Tests	Verify API responses match schemas	Postman / Dredd
Load Tests	Test performance under load	k6 / Locust
End-to-End Tests	Test complete user workflows	Cypress / Playwright

Example Test Script

import pytest
import requests

BASE_URL = "http://localhost:8080"

def test_health_check():
    response = requests.get(f"{BASE_URL}/health/live")
    assert response.status_code == 200

def test_list_models():
    response = requests.get(
        f"{BASE_URL}/v1/models",
        headers={"Authorization": "Bearer test-key"}
    )
    assert response.status_code == 200
    data = response.json()
    assert "data" in data

def test_completion_request():
    response = requests.post(
        f"{BASE_URL}/v1/completions",
        headers={
            "Authorization": "Bearer test-key",
            "Content-Type": "application/json"
        },
        json={
            "model": "gpt-3.5-turbo",
            "prompt": "Test prompt",
            "max_tokens": 10
        }
    )
    assert response.status_code == 200

Debugging & Troubleshooting

Common Issues

Port Already in Use

# Find process using port 8080 lsof -i :8080 # Kill process by PID kill -9 <PID> # Or change port in docker-compose.yml

Container Won't Start

# Check container logs docker-compose logs api-gateway # Check container status docker-compose ps # Rebuild container docker-compose up -d --build --force-recreate

API Rate Limiting Errors

# Check current rate limit status curl -I http://localhost:8080/v1/models # Look for X-RateLimit headers in response

Debug Mode Enable debug logging by setting LOG_LEVEL=debug in your .env file. This provides detailed request/response logs for troubleshooting.

Development Workflow

Recommended workflow for local development:

Start services: docker-compose up -d
Check health: curl http://localhost:8080/health/live
Run tests: pytest tests/
Make code changes: Edit files in ./config or source code
Rebuild if needed: docker-compose up -d --build
Test manually: Use Postman or curl for API testing
View logs: docker-compose logs -f api-gateway
Stop services: docker-compose down