O2Sound_ver2_final/backend/docs/API_Quick_Reference.md

# O2Sound API Quick Reference

## Authentication Endpoints

### Register
```bash
curl -X POST http://localhost:8000/auth/join \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "john_doe",
    "name": "John Doe",
    "password": "SecurePass123!",
    "email": "john@example.com",
    "phone_number": "010-1234-5678"
  }'
```

### Login
```bash
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "john_doe",
    "password": "SecurePass123!"
  }'
```

## User Management Endpoints

### Get User Items
```bash
curl -X POST http://localhost:8000/user/items \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{
    "id": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

### Update Item
```bash
curl -X PUT http://localhost:8000/user/item/update \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "item_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Business Name",
    "address": "New Address",
    "url": "https://newurl.com",
    "phone_number": "02-9876-5432"
  }'
```

### Delete Item
```bash
curl -X DELETE http://localhost:8000/user/item/delete \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "item_id": "550e8400-e29b-41d4-a716-446655440000"
  }'
```

## Video Management Endpoints

### Get User Videos
```bash
curl -X POST http://localhost:8000/user/videos \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{
    "id": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

### Delete Video
```bash
curl -X DELETE http://localhost:8000/user/video/delete \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{
    "user_id": "john_doe",
    "video_id": "660e8400-e29b-41d4-a716-446655440000"
  }'
```

### Stream Video
```bash
# Direct browser access or video player
http://localhost:8000/user/video/my_video_2024.mp4

# Using curl (saves to file)
curl -o downloaded_video.mp4 \
  http://localhost:8000/user/video/my_video_2024.mp4
```

## Profile Management Endpoints

### Get Profile
```bash
curl -X POST http://localhost:8000/user/profile \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{
    "id": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

### Update Profile
```bash
curl -X PUT http://localhost:8000/user/profile/update \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe Updated",
    "email": "john.updated@example.com",
    "phone_number": "010-9999-8888"
  }'
```

## Movie Maker Endpoints

### Start Video Generation Workflow
```bash
curl -X POST http://localhost:8000/moviemaker/start-workflow \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{
    "url": "https://example-business.com"
  }'
```

### Check Progress
```bash
curl -X POST http://localhost:8000/moviemaker/progress \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{
    "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }'
```

## Google OAuth Flow

### 1. Initiate Login
```bash
# Browser redirect
http://localhost:8000/social/google/login?return_url=http://localhost:3300/dashboard
```

### 2. After Google Authentication
```bash
# Google redirects to:
http://localhost:8000/social/google/callback?code=AUTH_CODE&state=STATE_VALUE
```

### 3. Get Token Info
```bash
curl -X GET http://localhost:8000/social/google/token/TEMP_TOKEN_ID
```

## Health Check

```bash
# Basic health check
curl http://localhost:8000/health

# Service info
curl http://localhost:8000/
```

## WebSocket Connection (if implemented)

```javascript
// JavaScript WebSocket example for real-time progress
const ws = new WebSocket('ws://localhost:8000/ws/progress/{task_id}');

ws.onmessage = (event) => {
  const progress = JSON.parse(event.data);
  console.log('Progress update:', progress);
};
```

## Python Client Example

```python
import requests
import json

class O2SoundClient:
    def __init__(self, base_url="http://localhost:8000"):
        self.base_url = base_url
        self.session = requests.Session()
    
    def login(self, user_id, password):
        response = self.session.post(
            f"{self.base_url}/auth/login",
            json={"user_id": user_id, "password": password}
        )
        return response.json()
    
    def start_video_generation(self, url):
        response = self.session.post(
            f"{self.base_url}/moviemaker/start-workflow",
            json={"url": url}
        )
        return response.json()
    
    def check_progress(self, task_id):
        response = self.session.post(
            f"{self.base_url}/moviemaker/progress",
            json={"task_id": task_id}
        )
        return response.json()

# Usage
client = O2SoundClient()
client.login("john_doe", "SecurePass123!")
result = client.start_video_generation("https://example.com")
task_id = result["task_id"]

# Check progress
import time
while True:
    progress = client.check_progress(task_id)
    print(progress)
    if progress["progress"]["combined"]:
        break
    time.sleep(5)
```

## JavaScript/TypeScript Client Example

```typescript
interface LoginRequest {
  user_id: string;
  password: string;
}

interface WorkflowRequest {
  url: string;
}

interface ProgressRequest {
  task_id: string;
}

class O2SoundAPI {
  private baseURL: string;
  
  constructor(baseURL: string = 'http://localhost:8000') {
    this.baseURL = baseURL;
  }
  
  async login(credentials: LoginRequest) {
    const response = await fetch(`${this.baseURL}/auth/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      credentials: 'include',
      body: JSON.stringify(credentials)
    });
    return response.json();
  }
  
  async startWorkflow(data: WorkflowRequest) {
    const response = await fetch(`${this.baseURL}/moviemaker/start-workflow`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      credentials: 'include',
      body: JSON.stringify(data)
    });
    return response.json();
  }
  
  async checkProgress(data: ProgressRequest) {
    const response = await fetch(`${this.baseURL}/moviemaker/progress`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      credentials: 'include',
      body: JSON.stringify(data)
    });
    return response.json();
  }
}

// Usage
const api = new O2SoundAPI();

async function generateVideo(url: string) {
  // Login first
  await api.login({
    user_id: 'john_doe',
    password: 'SecurePass123!'
  });
  
  // Start workflow
  const { task_id } = await api.startWorkflow({ url });
  
  // Poll for progress
  const checkStatus = async () => {
    const { progress } = await api.checkProgress({ task_id });
    
    if (progress.combined) {
      console.log('Video generation complete!');
    } else {
      console.log('Progress:', progress);
      setTimeout(checkStatus, 5000);
    }
  };
  
  checkStatus();
}
```

## Environment Variables

```bash
# .env.local example
PROJECT_NAME=O2Sound
API_V1_STR=/api/v1
SESSION_SECRET_KEY=your-secret-key-here
DATABASE_URL=postgresql://user:pass@localhost/o2sound
REDIS_URL=redis://localhost:6379
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:8000/social/google/callback
```

## Common Response Formats

### Success Response
```json
{
  "status": "success",
  "data": {
    // Response data here
  }
}
```

### Error Response
```json
{
  "status": "error",
  "error_code": "ERROR_CODE",
  "error_message": "Human readable error message",
  "details": {
    // Additional error details if available
  }
}
```

### Pagination Response (if implemented)
```json
{
  "total_count": 100,
  "page": 1,
  "page_size": 20,
  "total_pages": 5,
  "items": [
    // Array of items
  ]
}
```