ES_Sami7777/easystream-main
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dev
easystream-main/docs/API_DOCUMENTATION.md
SamiAhmed7777 f0f346deb9
Some checks failed
EasyStream Test Suite / test (pull_request) Has been cancelled
Details
EasyStream Test Suite / code-quality (pull_request) Has been cancelled
Details
EasyStream Test Suite / integration-test (pull_request) Has been cancelled
Details
Sync current dev state
2025-12-15 17:28:21 -08:00

13 KiB
Raw Permalink Blame History

EasyStream API Documentation

Overview

EasyStream provides a RESTful API for managing videos, users, comments, and subscriptions. All API endpoints return JSON responses and support both JWT token authentication and session-based authentication.

Base URL: /api/

Content-Type: application/json

Table of Contents

  1. Authentication
  2. Videos API
  3. User API
  4. Comments API
  5. Subscriptions API
  6. Error Handling
  7. Rate Limiting

Authentication

Overview

EasyStream supports two authentication methods:

  1. JWT Token Authentication (Recommended for API clients)
  2. Session-based Authentication (For web pages)

Endpoints

Login with JWT Token

POST /api/auth.php?action=login_token

Request Body:

{
  "identifier": "username or email",
  "password": "password",
  "expires_in": 86400
}

Response:

{
  "success": true,
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "expires_in": 86400,
  "user": {
    "usr_id": 1,
    "usr_user": "john",
    "usr_email": "john@example.com"
  }
}

Login with Session

POST /api/auth.php?action=login

Request Body:

{
  "identifier": "username or email",
  "password": "password",
  "remember": true,
  "csrf_token": "token"
}

Get CSRF Token

GET /api/auth.php?action=csrf_token

Verify Token

GET /api/auth.php?action=verify_token
Authorization: Bearer <token>

Get Current User

GET /api/auth.php?action=me
Authorization: Bearer <token>

Logout

POST /api/auth.php?action=logout

Videos API

Base endpoint: /api/videos.php

List Videos

Get a paginated list of videos with filtering options.

GET /api/videos.php?page=1&limit=20&sort=recent&category=music

Query Parameters:

  • page (integer, optional): Page number (default: 1)
  • limit (integer, optional): Items per page, max 100 (default: 20)
  • sort (string, optional): Sort order - recent, popular, featured, oldest, title (default: recent)
  • category (string, optional): Filter by category
  • channel_id (integer, optional): Filter by channel/user ID

Response:

{
  "success": true,
  "data": {
    "videos": [
      {
        "file_key": "123456",
        "file_title": "My Video",
        "file_description": "Description",
        "file_duration": "00:05:30",
        "file_views": 1500,
        "upload_date": "2025-01-15 10:30:00",
        "thumbnail": "/path/to/thumb.jpg",
        "usr_id": 1,
        "usr_user": "john",
        "usr_dname": "John Doe",
        "like_count": 50,
        "comment_count": 10
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "pages": 5
    }
  }
}

Get Single Video

GET /api/videos.php?id=123456

Response:

{
  "success": true,
  "data": {
    "file_key": "123456",
    "file_title": "My Video",
    "file_description": "Description",
    "file_name": "video.mp4",
    "file_duration": "00:05:30",
    "file_views": 1500,
    "privacy": "public",
    "upload_date": "2025-01-15 10:30:00",
    "usr_id": 1,
    "usr_user": "john",
    "usr_dname": "John Doe",
    "usr_avatar": "/path/to/avatar.jpg",
    "like_count": 50,
    "dislike_count": 2,
    "comment_count": 10,
    "subscriber_count": 1000,
    "user_like_status": "like",
    "user_subscribed": true
  }
}

Search Videos

GET /api/videos.php?action=search&q=search+query&page=1&limit=20

Create Video

POST /api/videos.php?action=create
Authorization: Bearer <token>

Request Body:

{
  "title": "Video Title",
  "description": "Video description",
  "privacy": "public",
  "category": "entertainment",
  "tags": "tag1,tag2,tag3"
}

Response:

{
  "success": true,
  "data": {
    "file_key": "789012",
    "message": "Video created successfully"
  }
}

Update Video

PUT /api/videos.php?id=123456
Authorization: Bearer <token>

Request Body:

{
  "file_title": "Updated Title",
  "file_description": "Updated description",
  "privacy": "private"
}

Delete Video

DELETE /api/videos.php?id=123456
Authorization: Bearer <token>

Like/Dislike Video

POST /api/videos.php?action=like
Authorization: Bearer <token>

Request Body:

{
  "file_key": "123456",
  "like_type": "like"
}

Response:

{
  "success": true,
  "data": {
    "action": "added",
    "like_count": 51,
    "dislike_count": 2
  }
}

Record Video View

POST /api/videos.php?action=view
Authorization: Bearer <token>

Request Body:

{
  "file_key": "123456"
}

Watch Later

Add/remove video from watch later list.

POST /api/videos.php?action=watch_later
Authorization: Bearer <token>

Request Body:

{
  "file_key": "123456"
}

User API

Base endpoint: /api/user.php

Get User Profile

Get current user's profile (requires authentication):

GET /api/user.php?action=profile
Authorization: Bearer <token>

Get another user's public profile:

GET /api/user.php?id=123

Response:

{
  "success": true,
  "data": {
    "usr_id": 1,
    "usr_user": "john",
    "usr_dname": "John Doe",
    "usr_email": "john@example.com",
    "usr_avatar": "/path/to/avatar.jpg",
    "usr_about": "About me",
    "usr_website": "https://example.com",
    "usr_verified": true,
    "usr_partner": false,
    "stats": {
      "videos": 50,
      "subscribers": 1000,
      "subscriptions": 75,
      "views": 50000
    }
  }
}

Update Profile

PUT /api/user.php
Authorization: Bearer <token>

Request Body:

{
  "usr_dname": "John Doe",
  "usr_about": "Updated bio",
  "usr_website": "https://newsite.com",
  "usr_location": "New York, USA"
}

Upload Avatar

POST /api/user.php?action=avatar
Authorization: Bearer <token>
Content-Type: multipart/form-data

Form Data:

  • avatar: Image file (JPG, PNG, GIF, max 5MB)

Get User Statistics

GET /api/user.php?action=stats
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "total_videos": 50,
    "videos_last_30_days": 5,
    "total_views": 50000,
    "total_subscribers": 1000,
    "total_subscriptions": 75,
    "total_comments": 250,
    "total_likes_given": 500
  }
}

Get User's Videos

GET /api/user.php?action=videos&id=123&page=1&limit=20

Get User's Subscriptions

GET /api/user.php?action=subscriptions
Authorization: Bearer <token>

Get User's Subscribers

GET /api/user.php?action=subscribers&id=123

Comments API

Base endpoint: /api/comments.php

List Comments

Get comments for a video:

GET /api/comments.php?file_key=123456&page=1&limit=50&sort=recent

Query Parameters:

  • file_key (required): Video file key
  • page (optional): Page number
  • limit (optional): Items per page, max 100
  • sort (optional): recent, top, oldest

Response:

{
  "success": true,
  "data": {
    "comments": [
      {
        "comment_id": 1,
        "usr_id": 5,
        "usr_user": "jane",
        "usr_dname": "Jane Smith",
        "usr_avatar": "/path/to/avatar.jpg",
        "comment_text": "Great video!",
        "comment_date": "2025-01-15 12:00:00",
        "comment_likes": 10,
        "reply_count": 3,
        "user_liked": false
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 120,
      "pages": 3
    }
  }
}

Get Single Comment

Get comment with replies:

GET /api/comments.php?id=123

Create Comment

POST /api/comments.php?action=create
Authorization: Bearer <token>

Request Body:

{
  "file_key": "123456",
  "comment_text": "This is my comment",
  "parent_id": null
}

Set parent_id to reply to another comment.

Update Comment

PUT /api/comments.php?id=123
Authorization: Bearer <token>

Request Body:

{
  "comment_text": "Updated comment text"
}

Delete Comment

DELETE /api/comments.php?id=123
Authorization: Bearer <token>

Like Comment

POST /api/comments.php?action=like
Authorization: Bearer <token>

Request Body:

{
  "comment_id": 123
}

Report Comment

POST /api/comments.php?action=report
Authorization: Bearer <token>

Request Body:

{
  "comment_id": 123,
  "reason": "Spam or abuse"
}

Subscriptions API

Base endpoint: /api/subscriptions.php

Get User's Subscriptions

GET /api/subscriptions.php?action=list
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "subscriptions": [
      {
        "usr_id": 5,
        "usr_user": "creator",
        "usr_dname": "Creator Name",
        "usr_avatar": "/path/to/avatar.jpg",
        "usr_verified": true,
        "sub_date": "2025-01-01 10:00:00",
        "video_count": 50,
        "subscriber_count": 10000
      }
    ],
    "total": 15
  }
}

Get Channel's Subscribers

GET /api/subscriptions.php?action=subscribers&channel_id=5&page=1

Get Subscription Feed

Get latest videos from subscribed channels:

GET /api/subscriptions.php?action=feed&page=1&limit=20
Authorization: Bearer <token>

Check Subscription Status

GET /api/subscriptions.php?action=check&channel_id=5
Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "is_subscribed": true,
    "subscribed_since": "2025-01-01 10:00:00"
  }
}

Subscribe to Channel

POST /api/subscriptions.php
Authorization: Bearer <token>

Request Body:

{
  "channel_id": 5
}

Unsubscribe from Channel

DELETE /api/subscriptions.php?channel_id=5
Authorization: Bearer <token>

Error Handling

All API endpoints return consistent error responses:

{
  "success": false,
  "error": "Error message here",
  "data": null
}

HTTP Status Codes

  • 200 OK: Request successful
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Authentication required or failed
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 405 Method Not Allowed: HTTP method not supported
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

Rate Limiting

Rate limits are applied to prevent abuse:

  • Login attempts: 5 per 15 minutes per IP
  • Password reset: 3 per hour per email
  • API calls: 100 per minute per user (when authenticated)
  • Anonymous API calls: 20 per minute per IP

Rate limit headers:

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

Frontend Integration

Using api-helper.js

EasyStream provides a modern JavaScript API client for easy integration:

// Initialize (automatically done on page load)
const api = window.api; // or new EasyStreamAPI()

// Login
const loginResult = await api.login('username', 'password');
if (loginResult.success) {
  console.log('Logged in!', loginResult.user);
}

// Get videos
const videos = await api.getVideos({ page: 1, sort: 'popular' });

// Get single video
const video = await api.getVideo('123456');

// Like video
await api.likeVideo('123456', 'like');

// Create comment
await api.createComment('123456', 'Great video!');

// Subscribe to channel
await api.subscribe(5);

// Get user profile
const profile = await api.getUserProfile(123);

// Update profile
await api.updateProfile({
  usr_dname: 'New Display Name',
  usr_about: 'Updated bio'
});

// Error handling
try {
  const result = await api.someAPICall();
} catch (error) {
  console.error('API error:', error.message);
  api.handleError(error);
}

Authentication Headers

When using JWT tokens, include the Authorization header:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

The api-helper.js automatically handles this for you.

CORS Configuration

Cross-Origin Resource Sharing (CORS) is configured securely:

  • Development: Allows localhost and 127.0.0.1
  • Production: Only allows origins defined in CORS_ALLOWED_ORIGINS environment variable

To configure allowed origins in production, set:

CORS_ALLOWED_ORIGINS=https://example.com,https://www.example.com

Best Practices

  1. Always use HTTPS in production
  2. Store JWT tokens securely (httpOnly cookies or secure localStorage)
  3. Include CSRF tokens for session-based requests
  4. Handle errors gracefully and show user-friendly messages
  5. Implement exponential backoff for failed requests
  6. Cache responses when appropriate
  7. Validate input on both client and server side
  8. Use pagination for large datasets
  9. Monitor rate limits to avoid being throttled
  10. Log errors for debugging

Support

For issues or questions about the API:

Last Updated: January 2025 API Version: 1.0.0

Reference in New Issue View Git Blame Copy Permalink