SOAP-REST Proxy

A production-ready, enterprise-grade proxy that bridges legacy SOAP services with modern REST APIs. Features a powerful admin dashboard, real-time monitoring, metrics, caching, circuit breakers, and zero-code configuration.

What Is This?

This SOAP-REST Proxy is a middleware application that sits between modern REST clients and legacy SOAP services. It automatically translates REST API calls (JSON) into SOAP requests (XML) and vice versa, eliminating the need to modify existing SOAP services or force modern applications to deal with XML.

Think of it as a translator that makes old SOAP services speak modern REST.

Why Use This?

Common Problems This Solves:

1. Legacy System Modernization

   • Your company has old SOAP services that can't be rewritten
   • New mobile/web apps need REST APIs, not SOAP
   • You want to gradually modernize without breaking existing systems

2. Developer Experience

   • Developers don't want to deal with SOAP/XML anymore
   • Modern frameworks (React, Vue, mobile apps) expect JSON REST APIs
   • SOAP tooling is outdated and difficult to use

3. API Gateway

   • Need a single, consistent REST interface to multiple SOAP backend services
   • Want to add caching, monitoring, rate limiting without touching SOAP services
   • Require real-time visibility into SOAP service calls

4. Third-Party Integration

   • External SOAP services (payment gateways, ERP systems, legacy partners)
   • Can't change how they work, but want REST interface
   • Need to monitor and troubleshoot integrations

Real-World Examples:

• E-commerce: Connect modern React checkout to legacy SAP/Oracle SOAP inventory systems
• Healthcare: Integrate mobile patient app with hospital's SOAP-based EHR
• Banking: Enable mobile banking app to access mainframe SOAP services
• Government: Modernize citizen-facing portals while keeping legacy backend

Key Features

Core Functionality

• Zero-Code Configuration: Define endpoint mappings in simple YAML files
• Automatic Translation: Seamlessly converts XML/SOAP ↔ JSON/REST
• SOAP Envelope Handling: Auto-wraps/unwraps SOAP envelopes
• Flexible Parameter Mapping: Map REST params to SOAP params with custom names
• Multi-Auth Support: Basic, Bearer, API Keys, OAuth2, custom headers
• WSDL Parsing: Auto-generate endpoints from WSDL files

Enterprise Features

Resilience & Performance:

• Connection Pooling: HTTP keep-alive with configurable pool sizes
• Response Caching: Redis/In-memory with stale-while-revalidate
• Circuit Breakers: Automatic failover and recovery
• Retry Logic: Exponential backoff for transient failures
• Rate Limiting: Per-client, per-endpoint, and global limits
• Load Balancing: Round-robin, least-connections, weighted, IP-hash strategies

Security & Compliance:

• Secrets Management: HashiCorp Vault, AWS Secrets Manager, Azure Key Vault
• WS-Security: Username/password tokens, signatures, encryption
• Client Certificates: Mutual TLS authentication
• Audit Logging: Comprehensive audit trails (SOC2, HIPAA, GDPR)
• Data Masking: PII/sensitive data masking in logs
• RBAC: Role-based access control

Monitoring & Operations:

• Prometheus Metrics: Production-grade monitoring
• Backend Health Checks: Active health monitoring for SOAP services
• Alerting: PagerDuty, Slack, Email, Webhook integrations
• OpenTelemetry Tracing: Distributed tracing (Jaeger, Zipkin)
• Real-Time WebSocket Monitoring: Live request/response streaming

Developer Experience:

• Error Mapping: Translate cryptic SOAP errors to user-friendly messages
• Transformation Templates: Handlebars/JSONata for complex mappings
• Schema Validation: Request/response validation with JSON Schema
• Mock Service: Record/playback, chaos testing
• WSDL-to-OpenAPI: Auto-convert WSDL to REST documentation

Admin Dashboard

• Dashboard: Real-time stats (uptime, memory, CPU, connections)
• Live Monitoring: WebSocket-based real-time request/response viewer
• Logs Viewer: Search, filter, and paginate through logs
• Configuration Manager: View and reload config without restart
• API Tester: Test endpoints directly from the UI
• WSDL Generator: Parse WSDL and auto-generate REST endpoints
• Metrics Dashboard: Visualize Prometheus metrics
• Settings: Cache management, config reload, system info

Quick Start

Prerequisites

• Node.js >= 18.0.0
• npm or yarn
• (Optional) Redis for distributed caching

Installation

1. Clone the repository:

git clone https://github.com/yourusername/soap-rest-proxy.git
cd soap-rest-proxy

2. Install dependencies:

npm install
cd admin-ui && npm install && cd ..

3. Configure your endpoints in config/mappings.yaml:

server:
  port: 3000
  host: 0.0.0.0
  cors: true

endpoints:
  - rest:
      method: GET
      path: /api/users/:id
    soap:
      url: http://your-soap-service.com/UserService
      action: GetUserById
      mapping:
        id: userId

4. Build and start:

# Build server
npm run build

# Start server (port 3000)
npm start

# In another terminal, start admin UI (port 3001)
cd admin-ui
npm run dev

5. Access the services:
   • REST API: http://localhost:3000
   • Admin Dashboard: http://localhost:3001
   • Health Check: http://localhost:3000/health
   • Metrics: http://localhost:3000/admin/metrics

How It Works

Request Flow

┌─────────────┐      REST/JSON       ┌──────────────┐      SOAP/XML      ┌──────────────┐
│             │  ───────────────────> │              │ ─────────────────> │              │
│  REST       │                       │  SOAP-REST   │                    │  SOAP        │
│  Client     │                       │  Proxy       │                    │  Service     │
│  (Mobile/   │  <───────────────────  │              │ <─────────────────  │  (Legacy)    │
│   Web App)  │      JSON Response    │              │    SOAP Response   │              │
└─────────────┘                       └──────────────┘                    └──────────────┘
                                             │
                                             ├─> Caching
                                             ├─> Circuit Breaker
                                             ├─> Metrics
                                             ├─> Logging
                                             └─> WebSocket Broadcast

Example Translation

REST Request:

GET /api/users/12345
Authorization: Bearer token123

Generated SOAP Request:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <Authorization>Bearer token123</Authorization>
  </soap:Header>
  <soap:Body>
    <GetUserById>
      <userId>12345</userId>
    </GetUserById>
  </soap:Body>
</soap:Envelope>

SOAP Response:

<soap:Envelope>
  <soap:Body>
    <GetUserByIdResponse>
      <user>
        <id>12345</id>
        <name>John Doe</name>
        <email>john@example.com</email>
      </user>
    </GetUserByIdResponse>
  </soap:Body>
</soap:Envelope>

Translated REST Response:

{
  "user": {
    "id": "12345",
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Quick Start Examples

For SAP Integration

See examples/sap-integration.yaml for a complete SAP ERP configuration.

For Oracle Integration

See examples/oracle-erp.yaml for Oracle E-Business Suite integration.

For Legacy Mainframe

See examples/legacy-mainframe.yaml for IBM mainframe/AS400 integration.

Configuration Guide

Complete Configuration Example

# Server Configuration
server:
  port: 3000
  host: 0.0.0.0
  cors: true
  timeout: 30000

# Authentication
auth:
  type: bearer              # none, basic, bearer, custom
  passthrough: true         # Forward auth headers to SOAP
  customHeaders:
    - X-API-Key
    - X-Client-ID

# Logging
logging:
  level: info               # error, warn, info, debug
  format: json              # json, simple
  logRequests: true
  logResponses: true

# Caching
cache:
  enabled: true
  type: redis               # redis, memory
  ttl: 300                  # seconds
  redis:
    host: localhost
    port: 6379
    password: your-password

# Rate Limiting
rateLimit:
  enabled: true
  windowMs: 900000          # 15 minutes
  max: 100                  # requests per window

# Circuit Breaker
circuitBreaker:
  enabled: true
  timeout: 3000
  errorThresholdPercentage: 50
  resetTimeout: 30000

# Endpoints
endpoints:
  # Simple GET
  - rest:
      method: GET
      path: /api/users/:id
    soap:
      url: http://soap-service.com/UserService
      action: GetUserById
      namespace: http://example.com/users
      mapping:
        id: userId

  # POST with body
  - rest:
      method: POST
      path: /api/users
    soap:
      url: http://soap-service.com/UserService
      action: CreateUser
      namespace: http://example.com/users
      timeout: 60000
      mapping:
        name: userName
        email: userEmail
        age: userAge

  # With custom headers
  - rest:
      method: GET
      path: /api/orders/:orderId
    soap:
      url: http://soap-service.com/OrderService
      action: GetOrder
      headers:
        X-Service-Version: "2.0"
      mapping:
        orderId: orderNumber

Environment Variables

Create .env file:

# Server
CONFIG_PATH=config/mappings.yaml
NODE_ENV=production
PORT=3000

# Redis (if using)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your-password

# Logging
LOG_LEVEL=info

Admin Dashboard Features

1. Dashboard

• Real-time server statistics
• Memory usage, CPU usage, uptime
• WebSocket connection count
• Cache statistics
• Auto-refresh every 5 seconds

2. Real-Time Monitoring

• Live WebSocket connection showing all requests/responses
• Filter by type (request, response, error, log)
• See JSON payloads in real-time
• Perfect for debugging and monitoring

3. Logs Viewer

• Search and filter logs by level
• Pagination support
• View metadata and stack traces
• Real-time log streaming via WebSocket

4. Endpoints Manager

• Parse WSDL files
• Auto-generate REST endpoint configurations
• Download generated config as JSON
• Test endpoints before deploying

5. API Tester

• Send HTTP requests directly from UI
• Support for all HTTP methods
• Custom headers and body
• See response status, headers, and data
• Measure request duration

6. Settings

• View current configuration
• Reload config without restart
• Cache management (view stats, clear cache)
• System information

7. Metrics (Prometheus)

• HTTP request metrics
• SOAP request metrics
• Error rates
• Cache hit/miss rates
• Circuit breaker states
• Node.js process metrics

Testing Endpoints

Using curl

# Test health endpoint
curl http://localhost:3000/health

# Test REST endpoint (proxied to SOAP)
curl -X GET http://localhost:3000/api/users/12345

# With authentication
curl -X GET \
  -H "Authorization: Bearer your-token" \
  http://localhost:3000/api/users/12345

# POST request
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com"}' \
  http://localhost:3000/api/users

Using Admin UI API Tester

1. Navigate to http://localhost:3001/api-tester
2. Select HTTP method
3. Enter URL
4. Add headers and body (if needed)
5. Click "Send Request"
6. View response

Monitoring & Observability

Prometheus Metrics

Metrics available at /admin/metrics:

# Get JSON format
curl http://localhost:3000/admin/metrics?format=json

# Get Prometheus format
curl http://localhost:3000/admin/metrics?format=prometheus

Available Metrics:

• http_requests_total - Total HTTP requests
• http_request_duration_seconds - HTTP request duration
• soap_requests_total - Total SOAP requests
• soap_request_errors_total - SOAP errors
• cache_hits_total / cache_misses_total - Cache performance
• circuit_breaker_state - Circuit breaker status
• Process metrics (CPU, memory, event loop)

Real-Time Monitoring

WebSocket endpoint at ws://localhost:3000/ws:

const ws = new WebSocket('ws://localhost:3000/ws');

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log(message.type, message.data);
};

Message types:

• request - Incoming REST requests
• response - Outgoing REST responses
• error - Errors
• log - Log messages

Advanced Features

WSDL Auto-Generation

Parse a WSDL and generate endpoint configurations:

curl -X POST http://localhost:3000/admin/wsdl/generate-endpoints \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://soap-service.com/Service?wsdl",
    "prefix": "/api",
    "namespace": "http://example.com/service"
  }'

Custom Data Transformations

endpoints:
  - rest:
      method: POST
      path: /api/transform
    soap:
      url: http://soap-service.com/Service
      action: ProcessData
      transformation:
        request: |
          data.timestamp = new Date().toISOString();
          data.source = 'rest-api';
        response: |
          result.processed = true;
          result.processedAt = Date.now();

Schema Validation

endpoints:
  - rest:
      method: POST
      path: /api/users
    soap:
      url: http://soap-service.com/UserService
      action: CreateUser
    validation:
      request:
        type: object
        required: [name, email]
        properties:
          name: { type: string }
          email: { type: string, format: email }

Docker Deployment

Using Docker Compose

version: '3.8'

services:
  proxy:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./config:/app/config
    environment:
      - NODE_ENV=production
      - REDIS_HOST=redis
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  admin-ui:
    build: ./admin-ui
    ports:
      - "3001:3001"
    environment:
      - VITE_API_URL=http://localhost:3000

Kubernetes Deployment

See k8s/ directory for Kubernetes manifests.

Performance & Scalability

Caching

• In-memory: Fast, single instance
• Redis: Distributed, multi-instance

Cache hit rates typically >80% for read-heavy workloads.

Circuit Breakers

Prevents cascade failures when SOAP services are down:

• Closed: Normal operation
• Open: Fast-fail without calling SOAP service
• Half-Open: Testing if service recovered

Rate Limiting

Protects SOAP services from overload:

• Per-client limits
• Global limits
• Sliding window algorithm

Development

Project Structure

soap-rest-proxy/
├── src/
│   ├── index.ts                 # Entry point
│   ├── server.ts                # Express server
│   ├── middleware/              # Auth, logging, rate limiting
│   ├── handlers/                # SOAP/REST conversion
│   ├── services/                # Cache, metrics, circuit breaker
│   ├── admin/                   # Admin API routes
│   ├── websocket/               # WebSocket server
│   ├── transformation/          # Data transformation engine
│   ├── validation/              # Schema validation
│   └── types/                   # TypeScript types
├── admin-ui/                    # React admin dashboard
│   ├── src/
│   │   ├── pages/               # Dashboard, Monitoring, etc.
│   │   ├── components/          # Reusable UI components
│   │   ├── services/            # API client
│   │   └── hooks/               # React hooks (WebSocket)
├── config/
│   └── mappings.yaml            # Endpoint configuration
├── tests/                       # Unit & integration tests
└── docs/                        # Additional documentation

Running Tests

npm test

Development Mode

# Server with hot reload
npm run dev

# Admin UI with hot reload
cd admin-ui && npm run dev

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support & Troubleshooting

Common Issues

Cannot connect to SOAP service

• Verify SOAP URL is accessible
• Check firewall/network settings
• Test SOAP endpoint with tools like SoapUI

SOAP Fault errors

• Verify SOAP action name
• Check parameter mapping
• Review namespace configuration
• Enable debug logging

Authentication failures

• Confirm auth type matches SOAP service requirements
• Verify passthrough is enabled
• Check custom headers

WebSocket not connecting

• Ensure server is running
• Check firewall allows WebSocket connections
• Verify URL is ws:// not wss:// for local development

Debug Mode

Enable detailed logging:

logging:
  level: debug
  logRequests: true
  logResponses: true

Getting Help

• Read the docs
• Open an issue
• Discussions

Roadmap

• Basic SOAP-REST translation
• Admin dashboard
• Real-time monitoring
• Metrics and observability
• Caching layer
• Circuit breakers
• WSDL parsing
• WS-Security support
• GraphQL gateway
• API versioning
• Multi-tenancy
• Request/response mocking
• Load balancing across SOAP endpoints
• Advanced analytics dashboard
• Connection pooling
• Secrets management (Vault/AWS/Azure)
• Enhanced error mapping
• Backend health monitoring
• Alerting (Slack/PagerDuty/Email)
• Transformation templates
• LDAP/SAML authentication
• Request batching
• Streaming for large payloads
• Migration toolkit

Authors

Built for developers who need to bridge the gap between modern and legacy systems.