Skip to content

RouterV2 API Documentation

Comprehensive API documentation for RouterV2 endpoints and request/response patterns

📡 API Overview

RouterV2 provides a flexible HTTP API that handles multiple request types and routing scenarios. The service acts as an intelligent router that processes requests, makes routing decisions, and delivers appropriate content or redirects.

🔗 Base Endpoints

Primary Routing Endpoint

  • URL: /
  • Methods: GET, POST
  • Purpose: Main routing and content delivery endpoint

Health Check Endpoints

  • URL: /live
  • Method: GET

  • Purpose: Liveness probe for Kubernetes

  • URL: /ready

  • Method: GET
  • Purpose: Readiness probe for Kubernetes

Post-Response Processing

  • URL: /postresponse
  • Method: POST
  • Purpose: Post-response processing and analytics

🎯 Request Types and Patterns

1. Landing Page Requests

Basic Landing Page Request

GET /?campaign=auto-insurance&zip=12345&age=30 HTTP/1.1
Host: router.example.com
User-Agent: Mozilla/5.0...

Query Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | campaign | string | No | Campaign identifier | | zip | string | No | ZIP code for location targeting | | age | number | No | User age for targeting | | wizsid | string | No | Session identifier (auto-generated if missing) | | product | string | No | Product type (auto, home, health, etc.) | | mobile | boolean | No | Mobile device indicator |

Response Types: - HTML Content: Rendered landing page - Redirect: 302 redirect to appropriate destination - Error Page: Error handling page

Example Response (HTML Content)

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Set-Cookie: wizsid=abc123; Path=/; HttpOnly
Cache-Control: no-cache

<!DOCTYPE html>
<html>
<head>
    <title>Auto Insurance Quotes</title>
    <!-- Generated content -->
</head>
<body>
    <!-- Landing page content -->
</body>
</html>

2. Form Requests

Form Display Request

GET /?form=auto-quote&step=1&wizsid=abc123 HTTP/1.1
Host: router.example.com

Form Submission Request

POST / HTTP/1.1
Host: router.example.com
Content-Type: application/x-www-form-urlencoded

wizsid=abc123&step=2&firstName=John&lastName=Doe&zip=12345

Form Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | form | string | Yes | Form identifier | | step | number | No | Current form step | | wizsid | string | Yes | Session identifier | | Form fields | mixed | Varies | Form-specific data fields |

3. Widget Requests

Widget Content Request

GET /?widget=quote-calculator&product=auto&embed=true HTTP/1.1
Host: router.example.com

Widget Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | widget | string | Yes | Widget type identifier | | embed | boolean | No | Embedded widget mode | | theme | string | No | Widget theme/styling | | callback | string | No | JSONP callback function |

Widget Response (JSON): 

{
  "type": "widget",
  "content": {
    "html": "<div class='quote-widget'>...</div>",
    "css": "/* Widget styles */",
    "js": "/* Widget JavaScript */"
  },
  "config": {
    "theme": "default",
    "responsive": true
  }
}

4. Advertisement Requests

Ad Content Request

GET /?ads=true&placement=header&size=728x90 HTTP/1.1
Host: router.example.com

Ad Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | ads | boolean | Yes | Advertisement request flag | | placement | string | No | Ad placement location | | size | string | No | Ad dimensions (WxH) | | format | string | No | Ad format (banner, native, video) |

Ad Response (JSON): 

{
  "type": "ads",
  "ads": [
    {
      "id": "ad-123",
      "html": "<div class='ad-banner'>...</div>",
      "clickUrl": "https://advertiser.com/click?id=123",
      "impressionUrl": "https://tracker.com/impression?id=123",
      "size": "728x90",
      "placement": "header"
    }
  ],
  "tracking": {
    "impressionPixels": ["https://pixel1.com", "https://pixel2.com"],
    "clickTracking": true
  }
}

5. Redirect Requests

Tracked Redirect Request

GET /?redirect=true&destination=partner&campaign=auto HTTP/1.1
Host: router.example.com

Redirect Response: 

HTTP/1.1 302 Found
Location: https://partner.example.com/auto-insurance?ref=campaign&sid=abc123
Set-Cookie: wizsid=abc123; Path=/; HttpOnly

🔧 Advanced Request Features

1. Session Management

Session Creation

Sessions are automatically created when a wizsid parameter is not provided:

GET /?campaign=auto HTTP/1.1

Response includes session cookie: 

Set-Cookie: wizsid=generated-session-id; Path=/; HttpOnly; SameSite=Lax

Session Continuation

Existing sessions are maintained via cookie or query parameter:

GET /?campaign=auto&wizsid=existing-session-id HTTP/1.1
Cookie: wizsid=existing-session-id

2. Mobile Detection

RouterV2 automatically detects mobile devices and adjusts content accordingly:

GET /?campaign=auto HTTP/1.1
User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)...

Mobile-optimized response: 

{
  "type": "content",
  "mobile": true,
  "content": {
    "html": "<!-- Mobile-optimized HTML -->",
    "viewport": "width=device-width, initial-scale=1.0"
  }
}

3. A/B Testing and Splits

Split Testing Request

GET /?campaign=auto&split=test-variant-a HTTP/1.1

Split Assignment Response

{
  "type": "content",
  "split": {
    "testName": "landing-page-test",
    "variant": "variant-a",
    "assigned": true
  },
  "content": {
    "html": "<!-- Variant A content -->"
  }
}

4. Debug and Verbose Mode

Debug Request

GET /?campaign=auto&debug=true&verbose=true HTTP/1.1

Verbose Response

{
  "type": "content",
  "content": {
    "html": "<!-- Page content -->"
  },
  "debug": {
    "pipeline": {
      "executionTime": 150,
      "stages": {
        "S00": { "duration": 5, "status": "SUCCESS" },
        "S01": { "duration": 12, "status": "SUCCESS" },
        "S03": { "duration": 25, "status": "SUCCESS" }
      }
    },
    "cache": {
      "hits": 8,
      "misses": 3,
      "hitRatio": 0.73
    },
    "decision": {
      "engine": "external",
      "response": { "route": "landing-page" },
      "duration": 45
    }
  }
}

📊 Response Formats

1. HTML Content Response

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Cache-Control: no-cache, no-store, must-revalidate
Set-Cookie: wizsid=session-id; Path=/; HttpOnly

<!DOCTYPE html>
<html>
<!-- Generated HTML content -->
</html>

2. JSON API Response

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache

{
  "type": "widget|ads|api",
  "status": "success",
  "data": { /* Response data */ },
  "meta": { /* Metadata */ }
}

3. Redirect Response

HTTP/1.1 302 Found
Location: https://destination.example.com/path?params
Set-Cookie: wizsid=session-id; Path=/; HttpOnly
Cache-Control: no-cache

4. Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "type": "error",
  "status": "error",
  "error": {
    "code": "INVALID_CAMPAIGN",
    "message": "Campaign not found or inactive",
    "details": {
      "campaign": "invalid-campaign-id"
    }
  }
}

🔍 Query Parameter Reference

Core Parameters

Parameter Type Description Example
wizsid string Session identifier abc123def456
campaign string Campaign identifier auto-insurance
product string Product type auto, home, health
zip string ZIP code 12345
age number User age 30
mobile boolean Mobile device flag true, false

Routing Parameters

Parameter Type Description Example
form string Form identifier auto-quote
step number Form step 1, 2, 3
widget string Widget type quote-calculator
ads boolean Ad request flag true
redirect boolean Redirect request true

Debug Parameters

Parameter Type Description Example
debug boolean Enable debug mode true
verbose boolean Verbose output true
test boolean Test mode true
split string A/B test variant variant-a

🚀 Integration Examples

JavaScript Integration

// Landing page request
fetch('/router?campaign=auto&zip=12345')
  .then(response => response.text())
  .then(html => {
    document.getElementById('content').innerHTML = html;
  });

// Widget request
fetch('/router?widget=quote-calculator&product=auto')
  .then(response => response.json())
  .then(data => {
    document.getElementById('widget').innerHTML = data.content.html;
  });

cURL Examples

# Basic landing page request
curl "https://router.example.com/?campaign=auto&zip=12345"

# Form submission
curl -X POST "https://router.example.com/" \
  -d "wizsid=abc123&step=2&firstName=John&zip=12345"

# Widget request
curl "https://router.example.com/?widget=quote-calculator&format=json"

# Debug request
curl "https://router.example.com/?campaign=auto&debug=true&verbose=true"

Next: Configuration Documentation - Configuration management and environment setup