cloud-orchestrator/test-new-api.md

Server Recommendation API - New Input Format

Change Summary

The server recommendation system now accepts tech stack + user scale instead of hardware specifications.

API Changes

Old Format (Hardware-based)

POST /api/recommend
{
  "cpu_cores": 4,
  "memory_gb": 16,
  "storage_gb": 200
}

New Format (Tech Stack-based)

POST /api/recommend
{
  "tech_stack": ["Node.js", "MongoDB", "Redis", "Docker"],
  "expected_users": 5000,
  "use_case": "실시간 채팅 서비스",
  "traffic_pattern": "steady",
  "region_preference": ["asia", "us"],
  "budget_limit": 300
}

Request Fields

Required Fields

Field	Type	Description	Example
tech_stack	string[]	Technologies used (min 1)	["Node.js", "MongoDB"]
expected_users	number	Expected user count	5000
use_case	string	Service description	"실시간 채팅 서비스"

Optional Fields

Field	Type	Options	Default	Description
traffic_pattern	string	steady, spiky, growing	steady	Traffic characteristics
region_preference	string[]	Region codes	-	Preferred regions
budget_limit	number	USD/month	-	Maximum monthly budget

Response Format

New Response Structure

{
  "recommendations": [
    {
      "server": {
        "id": "aws-t3-medium",
        "provider_name": "AWS",
        "name": "t3.medium",
        "instance_type": "t3.medium",
        "cpu_cores": 2,
        "memory_size": 4,
        "storage_size": 50,
        "storage_type": "SSD",
        "network_bandwidth": 5000,
        "sla_percentage": 99.95,
        "price_monthly": 30.36,
        "available_regions": ["us-east-1", "ap-northeast-1"]
      },
      "score": 95,
      "analysis": {
        "tech_fit": "Node.js와 MongoDB에 적합한 메모리와 SSD 스토리지 제공",
        "capacity": "5000 동시 사용자 처리 가능 (예상 부하의 150%)",
        "cost_efficiency": "가격 대비 성능 우수, 월 $30로 안정적 운영 가능",
        "scalability": "수평 확장 용이, Auto Scaling 지원으로 트래픽 변동 대응"
      },
      "estimated_capacity": {
        "max_concurrent_users": 7500,
        "requests_per_second": 1000
      }
    }
  ],
  "infrastructure_tips": [
    "Redis 캐싱으로 DB 부하 50% 감소 예상",
    "CDN 추가로 정적 자산 응답 속도 개선 권장",
    "MongoDB 인덱스 최적화로 쿼리 성능 향상"
  ],
  "total_candidates": 25,
  "cached": false
}

Example Requests

Example 1: Real-time Chat Service

curl -X POST https://your-worker.workers.dev/api/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "tech_stack": ["Node.js", "Socket.io", "MongoDB", "Redis"],
    "expected_users": 5000,
    "use_case": "실시간 채팅 서비스",
    "traffic_pattern": "spiky",
    "region_preference": ["asia"],
    "budget_limit": 300
  }'

Example 2: REST API Server

curl -X POST https://your-worker.workers.dev/api/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "tech_stack": ["Python", "FastAPI", "PostgreSQL", "Docker"],
    "expected_users": 10000,
    "use_case": "REST API 서버",
    "traffic_pattern": "steady"
  }'

Example 3: E-commerce Platform

curl -X POST https://your-worker.workers.dev/api/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "tech_stack": ["Java", "Spring Boot", "MySQL", "Redis", "Elasticsearch"],
    "expected_users": 50000,
    "use_case": "전자상거래 플랫폼",
    "traffic_pattern": "growing",
    "region_preference": ["asia", "us"],
    "budget_limit": 1000
  }'

Validation Rules

Tech Stack

• Must be a non-empty array
• At least 1 technology required
• Examples: Node.js, Python, Java, MongoDB, PostgreSQL, Redis, Docker

Expected Users

• Must be a positive number
• Represents concurrent users or daily active users
• Used to calculate capacity requirements

Use Case

• Must be a non-empty string
• Describes the service type
• Helps AI understand context and requirements

Traffic Pattern

• steady: Consistent traffic throughout the day
• spiky: Sudden traffic bursts (2x capacity buffer)
• growing: Gradually increasing users (1.5x capacity buffer)

Region Preference

• Array of region codes
• Examples: asia, us, eu
• Filters servers by availability

Budget Limit

• Non-negative number
• In USD per month
• Filters servers by price

AI Analysis Components

Tech Fit

Explains why the server specifications match the technology stack requirements.

Capacity

Describes how the server handles the expected user load and headroom.

Cost Efficiency

Assesses value for money and operational cost considerations.

Scalability

Evaluates growth potential and scaling strategies.

Estimated Capacity

Provides concrete numbers for:

• Maximum concurrent users
• Requests per second

Infrastructure Tips

Practical recommendations for:

• Performance optimization
• Cost reduction
• Reliability improvement
• Architecture enhancement

Migration Guide

From Old Format to New Format

Old Request:

{
  "cpu_cores": 4,
  "memory_gb": 16,
  "storage_gb": 200,
  "sla_requirement": 99.9,
  "budget_monthly": 200
}

New Request:

{
  "tech_stack": ["Node.js", "PostgreSQL"],
  "expected_users": 10000,
  "use_case": "웹 애플리케이션",
  "traffic_pattern": "steady",
  "budget_limit": 200
}

Key Differences

1. Resource Calculation: Now automatic based on tech stack and user scale
2. Context-Aware: AI understands technology-specific requirements
3. Capacity Estimation: Provides realistic user capacity numbers
4. Practical Tips: Includes infrastructure optimization suggestions
5. Simpler Input: No need to estimate hardware specifications

Benefits

1. User-Friendly: No need to know hardware requirements
2. Intelligent: AI analyzes tech stack characteristics
3. Accurate: Better matches based on actual usage patterns
4. Actionable: Provides capacity estimates and practical tips
5. Flexible: Adapts to different traffic patterns and growth scenarios