Files

SamiAhmed7777 0b7e2d0a5b feat: Add comprehensive documentation suite and reorganize project structure

- Created complete documentation in docs/ directory
- Added PROJECT_OVERVIEW.md with feature highlights and getting started guide
- Added ARCHITECTURE.md with system design and technical details
- Added SECURITY.md with comprehensive security implementation guide
- Added DEVELOPMENT.md with development workflows and best practices
- Added DEPLOYMENT.md with production deployment instructions
- Added API.md with complete REST API documentation
- Added CONTRIBUTING.md with contribution guidelines
- Added CHANGELOG.md with version history and migration notes
- Reorganized all documentation files into docs/ directory for better organization
- Updated README.md with proper documentation links and quick navigation
- Enhanced project structure with professional documentation standards

2025-10-21 00:39:45 -07:00

14 KiB

Raw Blame History

API Documentation

EasyStream provides a comprehensive REST API for integrating with external applications and building custom clients.

Base URL

https://your-domain.com/api/

Authentication

API Key Authentication

Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY

Session Authentication

For web applications, use session-based authentication:

Cookie: PHPSESSID=your_session_id

Rate Limiting

Default: 1000 requests per hour per API key
Authenticated users: 5000 requests per hour
Premium users: 10000 requests per hour

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Response Format

Success Response

{
    "success": true,
    "data": {
        // Response data
    },
    "meta": {
        "timestamp": "2024-01-01T12:00:00Z",
        "version": "1.0"
    }
}

Error Response

{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid input parameters",
        "details": {
            "field": "email",
            "issue": "Invalid email format"
        }
    },
    "meta": {
        "timestamp": "2024-01-01T12:00:00Z",
        "version": "1.0"
    }
}

Authentication Endpoints

POST /api/auth/login

Authenticate user and create session.

Request:

{
    "username": "user@example.com",
    "password": "password123",
    "remember": true
}

Response:

{
    "success": true,
    "data": {
        "user": {
            "id": 123,
            "username": "user@example.com",
            "role": "user",
            "permissions": ["video.upload", "video.view"]
        },
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "expires_at": "2024-01-02T12:00:00Z"
    }
}

POST /api/auth/logout

Logout user and invalidate session.

Response:

{
    "success": true,
    "data": {
        "message": "Successfully logged out"
    }
}

GET /api/auth/me

Get current user information.

Response:

{
    "success": true,
    "data": {
        "user": {
            "id": 123,
            "username": "user@example.com",
            "email": "user@example.com",
            "role": "user",
            "created_at": "2024-01-01T00:00:00Z",
            "last_login": "2024-01-01T12:00:00Z"
        }
    }
}

Video Management

GET /api/videos

List videos with pagination and filtering.

Parameters:

page (int): Page number (default: 1)
limit (int): Items per page (default: 20, max: 100)
category (string): Filter by category
user_id (int): Filter by user
status (string): Filter by status (published, processing, draft)
sort (string): Sort by (created_at, views, likes, title)
order (string): Sort order (asc, desc)

Response:

{
    "success": true,
    "data": {
        "videos": [
            {
                "id": 456,
                "title": "Sample Video",
                "description": "Video description",
                "thumbnail": "https://example.com/thumb.jpg",
                "duration": 120,
                "views": 1000,
                "likes": 50,
                "status": "published",
                "created_at": "2024-01-01T10:00:00Z",
                "user": {
                    "id": 123,
                    "username": "creator"
                }
            }
        ],
        "pagination": {
            "current_page": 1,
            "total_pages": 10,
            "total_items": 200,
            "items_per_page": 20
        }
    }
}

GET /api/videos/{id}

Get specific video details.

Response:

{
    "success": true,
    "data": {
        "video": {
            "id": 456,
            "title": "Sample Video",
            "description": "Detailed video description",
            "thumbnail": "https://example.com/thumb.jpg",
            "video_url": "https://example.com/video.mp4",
            "hls_url": "https://example.com/hls/video/playlist.m3u8",
            "duration": 120,
            "views": 1000,
            "likes": 50,
            "dislikes": 5,
            "status": "published",
            "category": "entertainment",
            "tags": ["funny", "viral"],
            "created_at": "2024-01-01T10:00:00Z",
            "updated_at": "2024-01-01T11:00:00Z",
            "user": {
                "id": 123,
                "username": "creator",
                "avatar": "https://example.com/avatar.jpg"
            }
        }
    }
}

POST /api/videos

Upload a new video.

Request (multipart/form-data):

title: "My Video Title"
description: "Video description"
category: "entertainment"
tags: "funny,viral"
privacy: "public"
file: [video file]
thumbnail: [image file] (optional)

Response:

{
    "success": true,
    "data": {
        "video": {
            "id": 789,
            "title": "My Video Title",
            "status": "processing",
            "upload_progress": 100,
            "processing_progress": 0,
            "created_at": "2024-01-01T12:00:00Z"
        }
    }
}

PUT /api/videos/{id}

Update video information.

Request:

{
    "title": "Updated Title",
    "description": "Updated description",
    "category": "education",
    "tags": ["tutorial", "howto"],
    "privacy": "unlisted"
}

DELETE /api/videos/{id}

Delete a video.

Response:

{
    "success": true,
    "data": {
        "message": "Video deleted successfully"
    }
}

GET /api/videos/{id}/progress

Get video processing progress.

Response:

{
    "success": true,
    "data": {
        "video_id": 789,
        "status": "processing",
        "progress": {
            "upload": 100,
            "processing": 45,
            "thumbnail": 100,
            "hls": 30
        },
        "estimated_completion": "2024-01-01T12:15:00Z"
    }
}

Live Streaming

GET /api/streams

List live streams.

Response:

{
    "success": true,
    "data": {
        "streams": [
            {
                "id": 101,
                "title": "Live Gaming Session",
                "description": "Playing the latest game",
                "thumbnail": "https://example.com/stream_thumb.jpg",
                "status": "live",
                "viewers": 150,
                "started_at": "2024-01-01T12:00:00Z",
                "stream_key": "abc123def456",
                "rtmp_url": "rtmp://example.com/live/abc123def456",
                "hls_url": "https://example.com/hls/live/abc123def456/index.m3u8",
                "user": {
                    "id": 123,
                    "username": "streamer"
                }
            }
        ]
    }
}

POST /api/streams

Create a new live stream.

Request:

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

Response:

{
    "success": true,
    "data": {
        "stream": {
            "id": 102,
            "title": "My Live Stream",
            "stream_key": "xyz789abc123",
            "rtmp_url": "rtmp://example.com/live/xyz789abc123",
            "hls_url": "https://example.com/hls/live/xyz789abc123/index.m3u8",
            "status": "created",
            "created_at": "2024-01-01T12:00:00Z"
        }
    }
}

PUT /api/streams/{id}/start

Start a live stream.

Response:

{
    "success": true,
    "data": {
        "stream": {
            "id": 102,
            "status": "live",
            "started_at": "2024-01-01T12:00:00Z"
        }
    }
}

PUT /api/streams/{id}/stop

Stop a live stream.

Response:

{
    "success": true,
    "data": {
        "stream": {
            "id": 102,
            "status": "ended",
            "ended_at": "2024-01-01T13:00:00Z",
            "duration": 3600
        }
    }
}

User Management

GET /api/users

List users (admin only).

Parameters:

page (int): Page number
limit (int): Items per page
role (string): Filter by role
status (string): Filter by status

GET /api/users/{id}

Get user profile.

Response:

{
    "success": true,
    "data": {
        "user": {
            "id": 123,
            "username": "user123",
            "email": "user@example.com",
            "avatar": "https://example.com/avatar.jpg",
            "bio": "User biography",
            "subscriber_count": 1000,
            "video_count": 50,
            "created_at": "2024-01-01T00:00:00Z"
        }
    }
}

PUT /api/users/{id}

Update user profile.

Request:

{
    "bio": "Updated biography",
    "avatar": "base64_encoded_image_data"
}

Comments and Interactions

GET /api/videos/{id}/comments

Get video comments.

Parameters:

page (int): Page number
limit (int): Items per page
sort (string): Sort by (created_at, likes)

Response:

{
    "success": true,
    "data": {
        "comments": [
            {
                "id": 789,
                "content": "Great video!",
                "likes": 10,
                "replies_count": 2,
                "created_at": "2024-01-01T12:00:00Z",
                "user": {
                    "id": 456,
                    "username": "commenter",
                    "avatar": "https://example.com/avatar.jpg"
                }
            }
        ]
    }
}

POST /api/videos/{id}/comments

Add a comment to a video.

Request:

{
    "content": "This is a great video!",
    "parent_id": null
}

POST /api/videos/{id}/like

Like a video.

Response:

{
    "success": true,
    "data": {
        "liked": true,
        "like_count": 51
    }
}

DELETE /api/videos/{id}/like

Unlike a video.

Response:

{
    "success": true,
    "data": {
        "liked": false,
        "like_count": 50
    }
}

Search

GET /api/search

Search for videos, users, or streams.

Parameters:

q (string): Search query
type (string): Search type (videos, users, streams, all)
page (int): Page number
limit (int): Items per page

Response:

{
    "success": true,
    "data": {
        "results": {
            "videos": [...],
            "users": [...],
            "streams": [...]
        },
        "total_results": 150,
        "search_time": 0.05
    }
}

Analytics

GET /api/analytics/videos/{id}

Get video analytics (owner only).

Response:

{
    "success": true,
    "data": {
        "video_id": 456,
        "views": {
            "total": 10000,
            "today": 100,
            "this_week": 500,
            "this_month": 2000
        },
        "engagement": {
            "likes": 500,
            "dislikes": 20,
            "comments": 150,
            "shares": 75
        },
        "demographics": {
            "age_groups": {
                "18-24": 30,
                "25-34": 40,
                "35-44": 20,
                "45+": 10
            },
            "countries": {
                "US": 50,
                "UK": 20,
                "CA": 15,
                "AU": 10,
                "other": 5
            }
        }
    }
}

Webhooks

Configuration

Configure webhooks in your account settings to receive real-time notifications.

Events

video.uploaded - New video uploaded
video.processed - Video processing completed
stream.started - Live stream started
stream.ended - Live stream ended
comment.created - New comment added
user.subscribed - New subscriber

Payload Example

{
    "event": "video.uploaded",
    "timestamp": "2024-01-01T12:00:00Z",
    "data": {
        "video": {
            "id": 789,
            "title": "New Video",
            "user_id": 123
        }
    }
}

Error Codes

HTTP Status Codes

200 - Success
201 - Created
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
422 - Validation Error
429 - Rate Limit Exceeded
500 - Internal Server Error

Application Error Codes

VALIDATION_ERROR - Input validation failed
AUTHENTICATION_REQUIRED - Authentication required
INSUFFICIENT_PERMISSIONS - Insufficient permissions
RESOURCE_NOT_FOUND - Resource not found
RATE_LIMIT_EXCEEDED - Rate limit exceeded
UPLOAD_FAILED - File upload failed
PROCESSING_ERROR - Video processing error

SDKs and Libraries

JavaScript SDK

import EasyStreamAPI from 'easystream-api';

const api = new EasyStreamAPI({
    baseURL: 'https://your-domain.com/api',
    apiKey: 'your-api-key'
});

// Upload video
const video = await api.videos.upload({
    title: 'My Video',
    file: videoFile
});

// Get video details
const videoDetails = await api.videos.get(video.id);

PHP SDK

<?php
use EasyStream\API\Client;

$client = new Client([
    'base_url' => 'https://your-domain.com/api',
    'api_key' => 'your-api-key'
]);

// List videos
$videos = $client->videos()->list([
    'limit' => 10,
    'category' => 'entertainment'
]);

// Create stream
$stream = $client->streams()->create([
    'title' => 'My Live Stream',
    'category' => 'gaming'
]);

Testing

API Testing

Use the provided test endpoints to verify your integration:

# Test authentication
curl -X POST https://your-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test@example.com","password":"password"}'

# Test video listing
curl -X GET https://your-domain.com/api/videos \
  -H "Authorization: Bearer YOUR_TOKEN"

Postman Collection

Import our Postman collection for easy API testing:

https://your-domain.com/api/postman-collection.json

Support

For API support and questions:

Documentation: https://docs.your-domain.com
Support Email: api-support@your-domain.com
GitHub Issues: https://github.com/your-org/easystream/issues

14 KiB Raw Blame History

API Documentation

Base URL

Authentication

API Key Authentication

Session Authentication

Rate Limiting

Response Format

Success Response

Error Response

Authentication Endpoints

POST /api/auth/login

POST /api/auth/logout

GET /api/auth/me

Video Management

GET /api/videos

GET /api/videos/{id}

POST /api/videos

PUT /api/videos/{id}

DELETE /api/videos/{id}

GET /api/videos/{id}/progress

Live Streaming

GET /api/streams

POST /api/streams

PUT /api/streams/{id}/start

PUT /api/streams/{id}/stop

User Management

GET /api/users

GET /api/users/{id}

PUT /api/users/{id}

Comments and Interactions

GET /api/videos/{id}/comments

POST /api/videos/{id}/comments

POST /api/videos/{id}/like

DELETE /api/videos/{id}/like

Search

GET /api/search

Analytics

GET /api/analytics/videos/{id}

Webhooks

Configuration

Events

Payload Example

Error Codes

HTTP Status Codes

Application Error Codes

SDKs and Libraries

JavaScript SDK

PHP SDK

Testing

API Testing

Postman Collection

Support

14 KiB

Raw Blame History