easystream-main/EASYSTREAM_API_DOCUMENTATION.md

📚 EasyStream REST API Documentation

🎯 Complete Guide to Using the EasyStream API

The EasyStream API is a comprehensive RESTful API that allows you to integrate with the EasyStream video platform. This API enables mobile app development, third-party integrations, content syndication, and automation.

---

🚀 Getting Started

Base URL

https://yourdomain.com/api/v1/

Content Type

All requests and responses use JSON format:

Content-Type: application/json

CORS Support

The API supports Cross-Origin Resource Sharing (CORS) for web applications.

---

🔐 Authentication

1. JWT Bearer Token (Recommended)

Step 1: Login to get JWT token

curl -X POST "https://yourdomain.com/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'

Response:

{
  "status": 200,
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "user": {
      "id": 123,
      "username": "your_username",
      "email": "user@example.com",
      "display_name": "Your Name"
    },
    "expires_in": 86400
  },
  "timestamp": 1642518000,
  "version": "v1"
}

Step 2: Use token in subsequent requests

curl -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

2. API Key Authentication

Generate API Key (via admin panel or user settings)

curl -H "Authorization: ApiKey your_api_key_here"

---

📊 Rate Limiting

Endpoint Type	Limit	Window
Authentication	10 requests	5 minutes
Upload	5 requests	1 hour
Default	100 requests	1 hour

Rate limit headers in response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642521600

---

🎬 Video Endpoints

Get Videos

GET /api/v1/videos

Parameters:

• page (int): Page number (default: 1)
• limit (int): Items per page (max: 50, default: 20)
• category (string): Filter by category
• sort (string): Sort order (recent, popular, rating)
• search (string): Search query

Example:

curl -X GET "https://yourdomain.com/api/v1/videos?limit=10&category=gaming&sort=popular" \
  -H "Authorization: Bearer your_token"

Response:

{
  "status": 200,
  "data": {
    "videos": [
      {
        "id": "video_123",
        "title": "Epic Gaming Moments",
        "description": "Amazing highlights from today's stream",
        "views": 1250,
        "rating": 4.8,
        "duration": 300,
        "size": 52428800,
        "uploaded_at": "2025-01-18 10:30:00",
        "uploader": {
          "username": "gamer_pro",
          "display_name": "Pro Gamer"
        },
        "thumbnail_url": "/thumbnails/video_123_medium.jpg",
        "video_url": "/watch/video_123"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 150
    }
  }
}

Get Single Video

GET /api/v1/videos/{video_id}

Example:

curl -X GET "https://yourdomain.com/api/v1/videos/video_123" \
  -H "Authorization: Bearer your_token"

Response:

{
  "status": 200,
  "data": {
    "id": "video_123",
    "title": "Epic Gaming Moments",
    "description": "Amazing highlights from today's stream",
    "full_description": "Full detailed description with timestamps...",
    "views": 1250,
    "rating": 4.8,
    "duration": 300,
    "size": 52428800,
    "category": "gaming",
    "tags": ["gaming", "highlights", "stream"],
    "privacy": "public",
    "uploaded_at": "2025-01-18 10:30:00",
    "uploader": {
      "id": 456,
      "username": "gamer_pro",
      "display_name": "Pro Gamer"
    },
    "thumbnail_urls": {
      "small": "/thumbnails/video_123_small.jpg",
      "medium": "/thumbnails/video_123_medium.jpg",
      "large": "/thumbnails/video_123_large.jpg"
    },
    "video_files": {
      "1080p": "/videos/video_123_1080p.mp4",
      "720p": "/videos/video_123_720p.mp4",
      "480p": "/videos/video_123_480p.mp4"
    },
    "hls_url": "/hls/video_123/master.m3u8"
  }
}

Upload Video

POST /api/v1/videos

Multipart form data:

curl -X POST "https://yourdomain.com/api/v1/videos" \
  -H "Authorization: Bearer your_token" \
  -F "video=@video.mp4" \
  -F "title=My Amazing Video" \
  -F "description=This is my video description" \
  -F "category=entertainment" \
  -F "tags=fun,awesome,video" \
  -F "privacy=public"

Response:

{
  "status": 201,
  "data": {
    "id": "video_456",
    "title": "My Amazing Video",
    "status": "processing",
    "upload_progress": 100,
    "processing_status": "queued"
  }
}

Update Video

PUT /api/v1/videos/{video_id}

Example:

curl -X PUT "https://yourdomain.com/api/v1/videos/video_123" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Video Title",
    "description": "Updated description",
    "privacy": "unlisted"
  }'

Delete Video

DELETE /api/v1/videos/{video_id}

Like Video

POST /api/v1/videos/{video_id}/like

Comment on Video

POST /api/v1/videos/{video_id}/comment

Body:

{
  "comment": "Great video! Love the content."
}

Get Video Comments

GET /api/v1/videos/{video_id}/comments?page=1&limit=20

---

👤 User Endpoints

Get Users

GET /api/v1/users?page=1&limit=20&search=username

Get User Profile

GET /api/v1/users/{user_id}

Response:

{
  "status": 200,
  "data": {
    "id": 123,
    "username": "gamer_pro",
    "display_name": "Pro Gamer",
    "email": "gamer@example.com",
    "avatar_url": "/avatars/123.jpg",
    "bio": "Professional gamer and content creator",
    "followers_count": 1250,
    "following_count": 89,
    "videos_count": 45,
    "total_views": 125000,
    "joined_at": "2024-01-15 09:30:00",
    "is_verified": true,
    "social_links": {
      "twitter": "https://twitter.com/gamer_pro",
      "youtube": "https://youtube.com/c/gamerpro"
    }
  }
}

Update Profile

PUT /api/v1/users/me

Body:

{
  "display_name": "New Display Name",
  "bio": "Updated bio",
  "social_links": {
    "twitter": "https://twitter.com/newhandle"
  }
}

Follow User

POST /api/v1/users/{user_id}/follow

Unfollow User

DELETE /api/v1/users/{user_id}/follow

Get User's Videos

GET /api/v1/users/{user_id}/videos?page=1&limit=20

Get User's Followers

GET /api/v1/users/{user_id}/followers?page=1&limit=20

Get User's Following

GET /api/v1/users/{user_id}/following?page=1&limit=20

---

🎥 Live Streaming Endpoints

Get Live Streams

GET /api/v1/live?category=gaming&status=live

Response:

{
  "status": 200,
  "data": {
    "streams": [
      {
        "id": 789,
        "title": "Live Gaming Session",
        "description": "Playing the latest games",
        "category": "gaming",
        "status": "live",
        "viewer_count": 45,
        "started_at": "2025-01-18 14:30:00",
        "streamer": {
          "username": "live_gamer",
          "display_name": "Live Gamer"
        },
        "thumbnail_url": "/live/thumbnails/789.jpg",
        "hls_url": "https://yourdomain.com/live/hls/stream_789.m3u8"
      }
    ]
  }
}

Create Live Stream

POST /api/v1/live

Body:

{
  "title": "My Live Stream",
  "description": "Live gaming session",
  "category": "gaming",
  "privacy": "public"
}

Response:

{
  "status": 201,
  "data": {
    "stream_id": 789,
    "stream_key": "stream_123_abc456_1642518000",
    "rtmp_url": "rtmp://yourdomain.com:1935/live",
    "stream_url": "rtmp://yourdomain.com:1935/live/stream_123_abc456_1642518000",
    "hls_url": "https://yourdomain.com/live/hls/stream_123_abc456_1642518000.m3u8",
    "dashboard_url": "/live/dashboard/789"
  }
}

Get Stream Details

GET /api/v1/live/{stream_id}

Start Stream

POST /api/v1/live/{stream_id}/start

Stop Stream

POST /api/v1/live/{stream_id}/stop

Update Stream

PUT /api/v1/live/{stream_id}

---

🔍 Search Endpoint

Search Content

GET /api/v1/search?q=gaming&type=videos&limit=20

Parameters:

• q (string): Search query
• type (string): Content type (videos, users, channels, all)
• category (string): Filter by category
• sort (string): Sort order (relevance, recent, popular)

Response:

{
  "status": 200,
  "data": {
    "query": "gaming",
    "results": {
      "videos": [...],
      "users": [...],
      "total_results": 150
    },
    "suggestions": ["gaming highlights", "gaming tutorial", "gaming review"]
  }
}

---

📊 Analytics Endpoints

Get Platform Overview

GET /api/v1/analytics/overview?start_date=2025-01-01&end_date=2025-01-31

Response:

{
  "status": 200,
  "data": {
    "users": {
      "total_users": 10000,
      "active_users": 2500,
      "new_users": 150
    },
    "content": {
      "total_videos": 5000,
      "new_videos": 45,
      "total_views": 1000000
    },
    "engagement": {
      "total_likes": 50000,
      "total_comments": 25000,
      "total_shares": 5000
    },
    "streaming": {
      "total_streams": 500,
      "live_streams": 12,
      "total_viewers": 1500
    }
  }
}

Get Video Analytics

GET /api/v1/analytics/videos/{video_id}?period=30d

Get User Analytics

GET /api/v1/analytics/users/{user_id}?period=7d

Generate Report

POST /api/v1/analytics/reports

Body:

{
  "report_type": "user_growth",
  "parameters": {
    "start_date": "2025-01-01",
    "end_date": "2025-01-31",
    "format": "json"
  }
}

---

🔧 Error Handling

HTTP Status Codes

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 405 - Method Not Allowed
• 429 - Rate Limited
• 500 - Internal Server Error

Error Response Format

{
  "status": 400,
  "data": {
    "error": "Invalid request parameters",
    "details": {
      "field": "title",
      "message": "Title is required"
    }
  },
  "timestamp": 1642518000,
  "version": "v1"
}

---

💻 Code Examples

JavaScript/Node.js

// Login and get token
const login = async (username, password) => {
  const response = await fetch('https://yourdomain.com/api/v1/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username, password })
  });
  
  const data = await response.json();
  return data.data.token;
};

// Get videos
const getVideos = async (token, limit = 20) => {
  const response = await fetch(`https://yourdomain.com/api/v1/videos?limit=${limit}`, {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  
  const data = await response.json();
  return data.data.videos;
};

// Upload video
const uploadVideo = async (token, videoFile, title, description) => {
  const formData = new FormData();
  formData.append('video', videoFile);
  formData.append('title', title);
  formData.append('description', description);
  
  const response = await fetch('https://yourdomain.com/api/v1/videos', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}` },
    body: formData
  });
  
  return await response.json();
};

Python

import requests

class EasyStreamAPI:
    def __init__(self, base_url):
        self.base_url = base_url.rstrip('/')
        self.token = None
    
    def login(self, username, password):
        response = requests.post(f'{self.base_url}/api/v1/auth/login', json={
            'username': username,
            'password': password
        })
        
        if response.status_code == 200:
            self.token = response.json()['data']['token']
            return True
        return False
    
    def get_videos(self, limit=20, category=None):
        headers = {'Authorization': f'Bearer {self.token}'}
        params = {'limit': limit}
        if category:
            params['category'] = category
        
        response = requests.get(f'{self.base_url}/api/v1/videos', 
                              headers=headers, params=params)
        
        if response.status_code == 200:
            return response.json()['data']['videos']
        return []
    
    def upload_video(self, video_path, title, description):
        headers = {'Authorization': f'Bearer {self.token}'}
        
        with open(video_path, 'rb') as video_file:
            files = {'video': video_file}
            data = {'title': title, 'description': description}
            
            response = requests.post(f'{self.base_url}/api/v1/videos',
                                   headers=headers, files=files, data=data)
        
        return response.json()

# Usage
api = EasyStreamAPI('https://yourdomain.com')
api.login('username', 'password')
videos = api.get_videos(limit=10, category='gaming')

PHP

class EasyStreamAPI {
    private $baseUrl;
    private $token;
    
    public function __construct($baseUrl) {
        $this->baseUrl = rtrim($baseUrl, '/');
    }
    
    public function login($username, $password) {
        $data = json_encode(['username' => $username, 'password' => $password]);
        
        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL => $this->baseUrl . '/api/v1/auth/login',
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => $data,
            CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
            CURLOPT_RETURNTRANSFER => true
        ]);
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        $result = json_decode($response, true);
        if ($result['status'] === 200) {
            $this->token = $result['data']['token'];
            return true;
        }
        
        return false;
    }
    
    public function getVideos($limit = 20, $category = null) {
        $url = $this->baseUrl . '/api/v1/videos?limit=' . $limit;
        if ($category) {
            $url .= '&category=' . urlencode($category);
        }
        
        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL => $url,
            CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $this->token],
            CURLOPT_RETURNTRANSFER => true
        ]);
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        $result = json_decode($response, true);
        return $result['status'] === 200 ? $result['data']['videos'] : [];
    }
}

// Usage
$api = new EasyStreamAPI('https://yourdomain.com');
$api->login('username', 'password');
$videos = $api->getVideos(10, 'gaming');

---

🔄 Content Syndication Use Cases

1. Cross-Platform Posting

Extract video metadata and post to YouTube, TikTok, Twitter, Facebook:

# Get video data
videos = api.get_videos(limit=10, category='gaming')

for video in videos:
    # Extract metadata
    title = video['title']
    description = video['description']
    tags = video.get('tags', [])
    
    # Post to YouTube
    youtube_api.upload_video(title, description, tags)
    
    # Post to Twitter
    tweet = f"🎥 {title[:100]}... Watch: {video['video_url']}"
    twitter_api.post_tweet(tweet)
    
    # Post to Facebook
    facebook_api.post_video_link(title, description, video['video_url'])

2. Content Aggregation

Build content aggregation services:

// Aggregate content from multiple EasyStream instances
const instances = [
  'https://gaming.example.com',
  'https://music.example.com',
  'https://education.example.com'
];

const aggregatedContent = [];

for (const instance of instances) {
  const api = new EasyStreamAPI(instance);
  const videos = await api.getVideos(20);
  aggregatedContent.push(...videos);
}

// Sort by popularity and recency
aggregatedContent.sort((a, b) => b.views - a.views);

3. Analytics Dashboard

Build external analytics dashboards:

# Collect analytics from multiple channels
analytics_data = []

for user_id in user_ids:
    user_analytics = api.get_user_analytics(user_id, period='30d')
    analytics_data.append(user_analytics)

# Generate reports
generate_performance_report(analytics_data)
send_weekly_summary_email(analytics_data)

---

🛠️ SDK and Tools

Official SDKs (Coming Soon)

• JavaScript/TypeScript SDK
• Python SDK
• PHP SDK
• Mobile SDKs (iOS/Android)

Postman Collection

Import the EasyStream API collection for easy testing:

https://yourdomain.com/api/v1/postman-collection.json

OpenAPI Specification

Full API specification available at:

https://yourdomain.com/api/v1/openapi.json

---

🔒 Security Best Practices

1. Token Management

• Store JWT tokens securely
• Refresh tokens before expiration
• Never expose tokens in client-side code

2. Rate Limiting

• Implement client-side rate limiting
• Handle 429 responses gracefully
• Use exponential backoff for retries

3. Input Validation

• Validate all input data
• Sanitize user-generated content
• Use HTTPS for all requests

4. Error Handling

• Handle all HTTP status codes
• Implement proper error logging
• Provide user-friendly error messages

---

📞 Support and Resources

API Status

Check API status and uptime:

https://yourdomain.com/api/v1/status

Rate Limit Status

Check your current rate limit status:

https://yourdomain.com/api/v1/rate-limit-status

Documentation Updates

This documentation is updated regularly. Check the version and last updated date:

{
  "version": "v1",
  "last_updated": "2025-01-18",
  "documentation_version": "1.0.0"
}

---

🎉 Conclusion

The EasyStream API provides comprehensive access to all platform features, enabling you to:

✅ Build mobile applications with full video platform functionality ✅ Create content syndication tools for cross-platform posting ✅ Develop analytics dashboards with real-time metrics ✅ Integrate live streaming into your applications ✅ Automate content management workflows ✅ Build third-party integrations and tools

The API is production-ready and designed for scalability, security, and ease of use.

For additional support, examples, or feature requests, please refer to the platform documentation or contact the development team.

🚀 Start building amazing applications with the EasyStream API today!