🔄Chapter 5: Phase 2 - API Bridge

弘益人間 (Hongik Ingan) - Benefit All Humanity

"The best abstraction is the one you don't notice."

Phase 2 of the WIA AI Interoperability Standard introduces the API Bridge layer—a unified interface that abstracts the complexity of integrating with dozens of AI providers. By providing a single, consistent API surface, developers can write once and deploy anywhere, switching between OpenAI, Anthropic, Google, AWS, and other providers without rewriting their application logic.

5.1 API Design Philosophy

The WIA API Bridge is built on three foundational principles that ensure maximum interoperability, developer experience, and long-term maintainability:

5.1.1 Provider-Agnostic Design

The core philosophy of the API Bridge is provider independence. Developers should never need to rewrite application code when switching from one AI provider to another. This principle drives every design decision in Phase 2.

5.1.2 RESTful API Standards

The WIA API Bridge adheres strictly to REST architectural principles and follows the OpenAPI 3.1 specification. This ensures compatibility with existing tools, frameworks, and developer workflows.

5.1.3 Extensibility and Future-Proofing

AI technology evolves rapidly. The API Bridge uses versioned endpoints, optional fields, and adapter plugins to support both current and future AI capabilities without breaking existing integrations.

5.2 RESTful Endpoints

The WIA API Bridge exposes a carefully designed set of endpoints that cover all common AI operations. Each endpoint follows consistent naming conventions and supports multiple AI providers through a unified interface.

5.2.1 Core Endpoint Architecture

All endpoints follow the pattern: https://api.wia.family/{version}/{resource}/{action}

https://api.wia.family/v1/
├── /models              # Model discovery and metadata
├── /convert             # Model format conversion
├── /validate            # Schema and model validation
├── /predict             # Inference and generation
├── /embeddings          # Vector embeddings
├── /chat                # Chat completions
└── /admin               # Administrative operations

5.2.2 Models Endpoint

Discover available AI models across all integrated providers.

Query Parameters:

• provider (optional): Filter by provider (openai, anthropic, google, etc.)
• capability (optional): Filter by capability (chat, embedding, vision, etc.)
• limit (optional): Max results (default: 50, max: 100)
• offset (optional): Pagination offset

curl -X GET "https://api.wia.family/v1/models?capability=chat&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

{
  "data": [
    {
      "id": "gpt-4-turbo",
      "provider": "openai",
      "name": "GPT-4 Turbo",
      "capabilities": ["chat", "function-calling", "vision"],
      "context_window": 128000,
      "max_tokens": 4096,
      "pricing": {
        "input": 0.01,
        "output": 0.03,
        "unit": "per_1k_tokens"
      }
    },
    {
      "id": "claude-3-opus",
      "provider": "anthropic",
      "name": "Claude 3 Opus",
      "capabilities": ["chat", "vision", "long-context"],
      "context_window": 200000,
      "max_tokens": 4096,
      "pricing": {
        "input": 0.015,
        "output": 0.075,
        "unit": "per_1k_tokens"
      }
    }
  ],
  "total": 47,
  "limit": 5,
  "offset": 0,
  "has_more": true
}

5.2.3 Convert Endpoint

Convert models between different formats (ONNX, TensorFlow, PyTorch, etc.).

{
  "source_model": {
    "format": "pytorch",
    "url": "s3://my-bucket/model.pth",
    "metadata": {
      "framework_version": "2.1.0"
    }
  },
  "target_format": "onnx",
  "optimization": {
    "quantize": true,
    "precision": "int8"
  },
  "callback_url": "https://myapp.com/webhooks/conversion"
}

{
  "conversion_id": "conv_9k3j2h1g8f7e",
  "status": "processing",
  "estimated_completion": "2025-12-25T14:30:00Z",
  "progress_url": "https://api.wia.family/v1/convert/conv_9k3j2h1g8f7e",
  "webhook_subscribed": true
}

5.2.4 Validate Endpoint

Validate model schemas, configurations, and compatibility.

{
  "validation_type": "schema",
  "model_id": "my-custom-model",
  "schema_version": "1.0",
  "strict_mode": true,
  "check_compatibility": ["openai", "anthropic"]
}

{
  "valid": true,
  "schema_version": "1.0",
  "compatibility": {
    "openai": {
      "compatible": true,
      "warnings": []
    },
    "anthropic": {
      "compatible": true,
      "warnings": ["Max tokens exceeds provider limit"]
    }
  },
  "validation_report": {
    "errors": [],
    "warnings": 1,
    "passed_checks": 24
  }
}

5.2.5 Predict Endpoint (Unified Inference)

Execute predictions across any supported provider with a unified interface.

{
  "model": "gpt-4-turbo",
  "provider": "openai",
  "input": {
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain quantum computing in simple terms."}
    ]
  },
  "parameters": {
    "temperature": 0.7,
    "max_tokens": 500,
    "top_p": 0.9
  },
  "metadata": {
    "user_id": "user_12345",
    "session_id": "sess_abc789"
  }
}

5.3 Authentication & Authorization

The WIA API Bridge implements enterprise-grade authentication and authorization supporting multiple standard protocols. Security is paramount—all connections require TLS 1.3+, and sensitive credentials are never logged.

5.3.1 Supported Authentication Methods

5.3.2 API Key Authentication

API keys are the simplest authentication method for server-side applications and CLI tools.

curl -X POST "https://api.wia.family/v1/predict" \
  -H "Authorization: Bearer wia_sk_REPLACE_WITH_YOUR_API_KEY_PLACEHOLDER" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-opus",
    "provider": "anthropic",
    "input": {"messages": [...]}
  }'

5.3.3 OAuth 2.0 Flow

For user-facing applications, OAuth 2.0 provides secure delegated access.

# Step 1: Redirect user to authorization endpoint
https://auth.wia.family/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=models.read predict.execute&
  state=RANDOM_STATE_STRING

# Step 2: Exchange authorization code for access token
POST https://auth.wia.family/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE_FROM_STEP_1&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=https://yourapp.com/callback

# Response
{
  "access_token": "wia_at_9k3j2h1g8f7e",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "wia_rt_6d5c4b3a2z1y",
  "scope": "models.read predict.execute"
}

5.3.4 Authorization Scopes

Fine-grained permissions control what operations authenticated clients can perform.

5.4 Request/Response Format

The WIA API Bridge uses standardized JSON structures for all requests and responses. This ensures consistency, predictability, and compatibility with existing tools and libraries.

5.4.1 Request Structure

All POST requests follow this general structure:

{
  "model": "string (required)",           // Model identifier
  "provider": "string (optional)",        // Provider name (auto-detected if omitted)
  "input": {                              // Provider-specific input
    // Varies by operation type
  },
  "parameters": {                         // Model parameters
    "temperature": 0.0-2.0,
    "max_tokens": integer,
    "top_p": 0.0-1.0,
    "frequency_penalty": -2.0 to 2.0,
    "presence_penalty": -2.0 to 2.0,
    // ... additional provider-specific parameters
  },
  "metadata": {                           // Optional metadata
    "user_id": "string",
    "session_id": "string",
    "tags": ["tag1", "tag2"]
  },
  "options": {                            // Request options
    "stream": boolean,                    // Enable streaming
    "timeout": integer,                   // Request timeout (seconds)
    "retry": {                            // Retry configuration
      "max_attempts": integer,
      "backoff": "exponential|linear"
    }
  }
}

5.4.2 Response Structure

All responses include standard fields for consistent error handling and metadata tracking.

{
  "id": "req_9k3j2h1g8f7e",              // Unique request identifier
  "object": "prediction",                 // Object type
  "created": 1703505600,                  // Unix timestamp
  "model": "gpt-4-turbo",                 // Model used
  "provider": "openai",                   // Provider used
  "data": {                               // Response data (varies by endpoint)
    // ... endpoint-specific response
  },
  "usage": {                              // Token/cost usage
    "prompt_tokens": 45,
    "completion_tokens": 128,
    "total_tokens": 173,
    "estimated_cost": 0.00347
  },
  "metadata": {                           // Request metadata echo
    "user_id": "user_12345",
    "session_id": "sess_abc789"
  },
  "timing": {                             // Performance metrics
    "queue_time_ms": 23,
    "processing_time_ms": 1247,
    "total_time_ms": 1270
  }
}

5.4.3 Streaming Responses

For real-time applications, the API supports Server-Sent Events (SSE) for streaming responses.

{
  "model": "gpt-4-turbo",
  "provider": "openai",
  "input": {
    "messages": [
      {"role": "user", "content": "Write a short story about AI."}
    ]
  },
  "options": {
    "stream": true
  }
}

data: {"id":"req_9k3j","object":"prediction.chunk","delta":{"content":"Once"}}

data: {"id":"req_9k3j","object":"prediction.chunk","delta":{"content":" upon"}}

data: {"id":"req_9k3j","object":"prediction.chunk","delta":{"content":" a"}}

data: {"id":"req_9k3j","object":"prediction.chunk","delta":{"content":" time"}}

data: {"id":"req_9k3j","object":"prediction.done","usage":{"total_tokens":523}}

data: [DONE]

5.5 Platform Adapters

Platform adapters are the core translation layer that enables provider-agnostic API access. Each adapter implements the WIA API Bridge interface for a specific AI provider.

5.5.1 Adapter Architecture

┌─────────────────────────────────────────────────────────┐
│              WIA API Bridge (Unified Interface)         │
└────────────────────┬────────────────────────────────────┘
                     │
         ┌───────────┴───────────┐
         │   Adapter Manager     │
         └───────────┬───────────┘
                     │
    ┌────────────────┼────────────────┐
    │                │                │
    ▼                ▼                ▼
┌─────────┐     ┌─────────┐     ┌─────────┐
│ OpenAI  │     │Anthropic│     │ Google  │
│ Adapter │     │ Adapter │     │ Adapter │
└────┬────┘     └────┬────┘     └────┬────┘
     │               │               │
     ▼               ▼               ▼
┌─────────┐     ┌─────────┐     ┌─────────┐
│ OpenAI  │     │Anthropic│     │ Google  │
│   API   │     │   API   │     │   API   │
└─────────┘     └─────────┘     └─────────┘

5.5.2 Supported Platform Adapters

5.5.3 Adapter Configuration

Each adapter can be configured with provider-specific settings while maintaining the unified API interface.

import { WIABridge, AdapterConfig } from '@wia/api-bridge';

const config: AdapterConfig = {
  adapters: {
    openai: {
      apiKey: process.env.OPENAI_API_KEY,
      organization: 'org-123456',
      baseURL: 'https://api.openai.com/v1',
      timeout: 60000,
      maxRetries: 3
    },
    anthropic: {
      apiKey: process.env.ANTHROPIC_API_KEY,
      baseURL: 'https://api.anthropic.com',
      version: '2023-06-01'
    },
    google: {
      projectId: 'my-gcp-project',
      credentials: '/path/to/service-account.json',
      location: 'us-central1'
    }
  },
  defaultProvider: 'openai',
  fallbackChain: ['openai', 'anthropic', 'google']
};

const bridge = new WIABridge(config);

5.5.4 Automatic Provider Selection

The API Bridge can automatically select the best provider based on model availability, cost, latency, or custom routing rules.

// Automatic provider selection based on cost
const response = await bridge.predict({
  model: 'auto',  // Let WIA choose
  routing: {
    strategy: 'cost',
    constraints: {
      maxLatency: 2000,  // ms
      minQuality: 'high'
    }
  },
  input: {
    messages: [...]
  }
});

// Response includes provider used
console.log(`Provider: ${response.provider}`);
console.log(`Cost: $${response.usage.estimated_cost}`);

5.6 Error Handling & Status Codes

Robust error handling is critical for production AI applications. The WIA API Bridge uses standard HTTP status codes and provides detailed error information for debugging and recovery.

5.6.1 HTTP Status Codes

5.6.2 Error Response Format

All errors return a consistent JSON structure with actionable details.

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_field",
    "message": "The 'model' field is required for all prediction requests",
    "param": "model",
    "provider": "openai",
    "provider_error": {
      "code": "invalid_model",
      "message": "The model 'gpt-5' does not exist"
    },
    "documentation_url": "https://docs.wia.family/errors/missing_required_field",
    "request_id": "req_9k3j2h1g8f7e"
  },
  "status": 400
}

5.6.3 Error Types

5.6.4 Retry Logic & Circuit Breaker

The API Bridge implements intelligent retry with exponential backoff and circuit breaker patterns.

from wia_bridge import WIABridge, RetryConfig

bridge = WIABridge(
    api_key="wia_sk_...",
    retry=RetryConfig(
        max_attempts=3,
        backoff_strategy="exponential",
        backoff_base=2,  # 2^n seconds
        retryable_status_codes=[408, 429, 500, 502, 503, 504],
        circuit_breaker_threshold=5,  # Open circuit after 5 failures
        circuit_breaker_timeout=60    # Try again after 60 seconds
    )
)

try:
    response = bridge.predict(...)
except WIARetryExceeded as e:
    print(f"Failed after {e.attempts} attempts: {e.last_error}")
except WIACircuitOpen as e:
    print(f"Circuit breaker open, service unavailable")

5.7 Rate Limiting & Quotas

To ensure fair usage and protect infrastructure, the WIA API Bridge implements multi-tier rate limiting and quota management.

5.7.1 Rate Limit Tiers

5.7.2 Rate Limit Headers

Every API response includes rate limit information in HTTP headers.

HTTP/1.1 200 OK
X-RateLimit-Limit: 60              # Requests allowed per window
X-RateLimit-Remaining: 47          # Requests remaining in window
X-RateLimit-Reset: 1703505660      # Unix timestamp when limit resets
X-RateLimit-Window: 60             # Window size in seconds
X-RateLimit-Retry-After: 23        # Seconds until retry (if rate limited)
X-Quota-Tokens-Used: 1247          # Tokens used this month
X-Quota-Tokens-Limit: 1000000      # Monthly token quota

5.7.3 Handling Rate Limits

import { WIABridge } from '@wia/api-bridge';

const bridge = new WIABridge({ apiKey: process.env.WIA_API_KEY });

async function predictWithRateLimiting(input) {
  try {
    const response = await bridge.predict(input);

    // Check remaining quota
    const remaining = response.headers['x-ratelimit-remaining'];
    if (remaining < 5) {
      console.warn('Approaching rate limit, consider throttling');
    }

    return response.data;
  } catch (error) {
    if (error.status === 429) {
      const retryAfter = error.headers['x-ratelimit-retry-after'];
      console.log(`Rate limited. Retry after ${retryAfter}s`);

      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      return predictWithRateLimiting(input);  // Retry
    }
    throw error;
  }
}

5.7.4 Cost Management & Budgets

Set spending limits to prevent unexpected costs.

{
  "budgets": {
    "monthly_limit": 500.00,        // USD
    "daily_limit": 20.00,
    "per_request_limit": 0.50,
    "alert_thresholds": [0.5, 0.8, 0.95],
    "alert_webhook": "https://myapp.com/webhooks/budget"
  },
  "cost_optimization": {
    "prefer_cheaper_models": true,
    "cache_responses": true,
    "cache_ttl": 3600
  }
}

5.8 SDK Overview

The WIA API Bridge provides official SDKs in multiple languages, abstracting HTTP details and providing idiomatic interfaces.

5.8.1 TypeScript/JavaScript SDK

npm install @wia/api-bridge
# or
yarn add @wia/api-bridge

import { WIABridge } from '@wia/api-bridge';

const bridge = new WIABridge({
  apiKey: process.env.WIA_API_KEY,
  defaultProvider: 'openai'
});

// Simple prediction
const response = await bridge.predict({
  model: 'gpt-4-turbo',
  input: {
    messages: [
      { role: 'user', content: 'Explain quantum entanglement' }
    ]
  },
  parameters: {
    temperature: 0.7,
    max_tokens: 500
  }
});

console.log(response.data.choices[0].message.content);

// Streaming
const stream = await bridge.predictStream({
  model: 'claude-3-opus',
  provider: 'anthropic',
  input: { messages: [...] }
});

for await (const chunk of stream) {
  process.stdout.write(chunk.delta.content);
}

5.8.2 Python SDK

pip install wia-bridge

from wia_bridge import WIABridge

bridge = WIABridge(api_key="wia_sk_...")

# Synchronous prediction
response = bridge.predict(
    model="gpt-4-turbo",
    input={
        "messages": [
            {"role": "user", "content": "Explain quantum entanglement"}
        ]
    },
    parameters={"temperature": 0.7, "max_tokens": 500}
)

print(response.data.choices[0].message.content)

# Async support
import asyncio

async def main():
    async with WIABridge(api_key="...") as bridge:
        response = await bridge.predict_async(...)
        print(response.data)

asyncio.run(main())

# Streaming
for chunk in bridge.predict_stream(model="claude-3-opus", ...):
    print(chunk.delta.content, end="")

5.8.3 SDK Features

Legend: ✅ Stable, 🔶 Beta, ❌ Not Available

5.9 Chapter Summary

What's Next?

Phase 2 provides the API foundation for interoperability. In Chapter 6: Phase 3 - Protocol Gateway, we'll explore how to extend beyond REST APIs to support gRPC, GraphQL, WebSockets, and message queues for enterprise integration scenarios.

5.10 Review Questions