Files

szbk 1c39ef5d37 Sİdebar'da music kategorisi oluşturuldu

2025-12-01 01:50:33 +03:00

13 KiB

Raw Blame History

du.pe - API Documentation

🔌 API Overview

The du.pe server provides a RESTful API with WebSocket support for managing torrents, streaming media, and handling file operations. The API is designed to be simple, intuitive, and provides real-time updates through WebSocket connections.

Base URL: http://localhost:3001 (configurable via environment)

📡 WebSocket Connection

Connection Endpoint

ws://localhost:3001/?token={auth_token}

WebSocket Events

Progress Updates

{
  "type": "progress",
  "torrents": [
    {
      "infoHash": "abc123...",
      "name": "Example Movie",
      "progress": 0.75,
      "downloadSpeed": 1048576,
      "uploadSpeed": 524288,
      "numPeers": 15,
      "state": "downloading",
      "timeRemaining": 1800
    }
  ]
}

File Updates

{
  "type": "fileUpdate",
  "action": "added|removed|modified",
  "path": "/downloads/example/",
  "mediaType": "movie|tvshow|file"
}

🛣️ REST API Endpoints

Torrent Management

GET /api/torrents

Description: Retrieve list of active torrents and their status

Response:

{
  "torrents": [
    {
      "infoHash": "abc123def456...",
      "name": "Example Movie 2024",
      "progress": 0.85,
      "downloadSpeed": 2097152,
      "uploadSpeed": 1048576,
      "numPeers": 25,
      "state": "downloading",
      "timeRemaining": 600,
      "files": [
        {
          "name": "movie.mp4",
          "length": 1073741824,
          "path": "/downloads/example/movie.mp4",
          "type": "video"
        }
      ],
      "magnetURI": "magnet:?xt=urn:btih:abc123...",
      "added": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Response Codes:

200 - Success
500 - Server error

POST /api/transfer

Description: Add a torrent via file upload

Content-Type: multipart/form-data

Request Body:

torrent: [file] - .torrent file

Response:

{
  "success": true,
  "infoHash": "abc123def456...",
  "name": "Uploaded Torrent Name"
}

Response Codes:

200 - Torrent added successfully
400 - Invalid torrent file
500 - Server error

POST /api/magnet

Description: Add a torrent via magnet link

Content-Type: application/json

Request Body:

{
  "magnet": "magnet:?xt=urn:btih:abc123def456..."
}

Response:

{
  "success": true,
  "infoHash": "abc123def456...",
  "name": "Torrent Name from Magnet"
}

Response Codes:

200 - Torrent added successfully
400 - Invalid magnet link
500 - Server error

DELETE /api/torrents/:infoHash

Description: Remove a torrent and optionally delete downloaded files

Request Parameters:

infoHash (path): Torrent info hash
deleteFiles (query, optional): true to delete downloaded files

Response:

{
  "success": true,
  "message": "Torrent removed successfully"
}

Response Codes:

200 - Torrent removed successfully
404 - Torrent not found
500 - Server error

File Streaming

GET /stream/:infoHash/:fileIndex

Description: Stream a file from a torrent

Request Parameters:

infoHash (path): Torrent info hash
fileIndex (path): Index of the file within the torrent
range (header, optional): HTTP Range header for partial content

Response:

Binary file stream with appropriate MIME headers
Supports HTTP Range requests for seeking in video files

Response Codes:

200 - Streaming successfully
206 - Partial content (range requests)
404 - File not found
500 - Server error

Example Usage:

// HTML5 Video Player
<video controls>
  <source src="http://localhost:3001/stream/abc123def456/0" type="video/mp4">
</video>

Media Library

GET /api/movies

Description: Retrieve movie library with metadata

Query Parameters:

page (optional): Page number for pagination
limit (optional): Items per page
search (optional): Search term
genre (optional): Filter by genre
year (optional): Filter by year

Response:

{
  "movies": [
    {
      "id": "movie_123",
      "title": "Example Movie",
      "year": 2024,
      "runtime": 120,
      "rating": 8.5,
      "genres": ["Action", "Drama"],
      "poster": "/cache/movie_data/123/poster.jpg",
      "backdrop": "/cache/movie_data/123/backdrop.jpg",
      "overview": "Movie description...",
      "filePath": "/downloads/example/movie.mp4",
      "fileSize": 1073741824,
      "added": "2024-01-15T10:30:00.000Z",
      "watched": false,
      "thumbnail": "/cache/thumbnails/videos/123/movie.jpg"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3
  }
}

GET /api/tvshows

Description: Retrieve TV show library with metadata

Query Parameters:

page (optional): Page number for pagination
limit (optional): Items per page
search (optional): Search term

Response:

{
  "shows": [
    {
      "id": "show_456",
      "title": "Example TV Series",
      "year": 2023,
      "rating": 9.0,
      "seasons": 2,
      "poster": "/cache/tv_data/456/poster.jpg",
      "backdrop": "/cache/tv_data/456/backdrop.jpg",
      "overview": "Series description...",
      "episodes": [
        {
          "season": 1,
          "episode": 1,
          "title": "Pilot Episode",
          "overview": "Episode description...",
          "airDate": "2023-01-15",
          "filePath": "/downloads/example/series/s01e01.mp4",
          "thumbnail": "/cache/tv_data/456/episodes/s01e01.jpg"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 12,
    "totalPages": 1
  }
}

GET /api/files

Description: Browse downloaded files and folders

Query Parameters:

path (optional): Directory path to browse (default: root downloads)
type (optional): Filter by file type (video, audio, image, document)

Response:

{
  "path": "/downloads/",
  "parent": "..",
  "items": [
    {
      "name": "Example Folder",
      "type": "directory",
      "path": "/downloads/Example Folder/",
      "size": null,
      "modified": "2024-01-15T10:30:00.000Z",
      "count": 5
    },
    {
      "name": "movie.mp4",
      "type": "file",
      "path": "/downloads/movie.mp4",
      "size": 1073741824,
      "modified": "2024-01-15T10:30:00.000Z",
      "mimeType": "video/mp4",
      "thumbnail": "/cache/thumbnails/videos/abc123/movie.jpg"
    }
  ]
}

Search Functionality

GET /api/search

Description: Search across torrents, files, and media library

Query Parameters:

q (required): Search query
type (optional): Search scope (all, torrents, movies, tvshows, files)
limit (optional): Maximum results (default: 50)

Response:

{
  "query": "example",
  "results": {
    "torrents": [
      {
        "infoHash": "abc123...",
        "name": "Example Torrent",
        "progress": 0.75,
        "state": "downloading"
      }
    ],
    "movies": [
      {
        "id": "movie_123",
        "title": "Example Movie",
        "year": 2024,
        "poster": "/cache/movie_data/123/poster.jpg"
      }
    ],
    "tvshows": [],
    "files": [
      {
        "name": "example.txt",
        "path": "/downloads/example.txt",
        "size": 1024,
        "type": "file"
      }
    ]
  },
  "total": 3
}

System Information

GET /api/system/info

Description: Get system information and status

Response:

{
  "version": "1.2.0",
  "uptime": 86400,
  "torrents": {
    "active": 3,
    "completed": 15,
    "total": 18
  },
  "storage": {
    "total": 1099511627776,
    "used": 536870912000,
    "free": 562641715776,
    "downloads": 500000000000,
    "cache": 36870912000
  },
  "network": {
    "downloadSpeed": 2097152,
    "uploadSpeed": 1048576
  }
}

GET /api/system/disk

Description: Get detailed disk usage information

Response:

{
  "downloads": {
    "path": "/app/server/downloads",
    "total": 1000000000000,
    "used": 500000000000,
    "free": 500000000000,
    "percentage": 50
  },
  "cache": {
    "path": "/app/server/cache",
    "total": 100000000000,
    "used": 20000000000,
    "free": 80000000000,
    "percentage": 20
  }
}

Trash Management

GET /api/trash

Description: List items in trash

Response:

{
  "items": [
    {
      "id": "trash_123",
      "originalPath": "/downloads/example.mp4",
      "name": "example.mp4",
      "size": 1073741824,
      "deleted": "2024-01-15T10:30:00.000Z",
      "type": "file"
    }
  ],
  "total": 1,
  "totalSize": 1073741824
}

POST /api/trash/:id/restore

Description: Restore item from trash

Request Parameters:

id (path): Trash item ID

Response:

{
  "success": true,
  "message": "Item restored successfully",
  "restoredPath": "/downloads/example.mp4"
}

DELETE /api/trash/:id

Description: Permanently delete item from trash

Request Parameters:

id (path): Trash item ID

Response:

{
  "success": true,
  "message": "Item permanently deleted"
}

DELETE /api/trash

Description: Empty trash (permanently delete all items)

Response:

{
  "success": true,
  "message": "Trash emptied successfully",
  "deletedCount": 5
}

🔒 Authentication (Planned)

Token-Based Authentication

Currently, the application uses basic token authentication. Full authentication system is planned for future versions.

Headers:

Authorization: Bearer {token}

POST /api/auth/login

Logout Endpoint (Planned)

POST /api/auth/logout

📊 Error Handling

Standard Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid magnet link format",
    "details": "The provided magnet link is not properly formatted"
  }
}

Common Error Codes

400 Bad Request - Invalid input parameters
401 Unauthorized - Authentication required
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server-side error

WebSocket Error Events

{
  "type": "error",
  "code": "TORRENT_ERROR",
  "message": "Failed to add torrent",
  "details": "Invalid torrent file format"
}

🔄 Rate Limiting

Current Limits

API requests: No current limits (planned)
File uploads: 100MB per file
Concurrent torrents: No hard limit
WebSocket connections: Standard browser limits

Planned Enhancements

API rate limiting by IP/user
Upload size limits
Concurrent download limits
Connection throttling

🧭 Usage Examples

JavaScript/TypeScript Client

// API client setup
const API_BASE = 'http://localhost:3001';

class DupeAPI {
  constructor(apiUrl) {
    this.apiUrl = apiUrl;
  }

  async getTorrents() {
    const response = await fetch(`${this.apiUrl}/api/torrents`);
    return response.json();
  }

  async addMagnet(magnetLink) {
    const response = await fetch(`${this.apiUrl}/api/magnet`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ magnet: magnetLink })
    });
    return response.json();
  }

  async getMovies(page = 1, limit = 20) {
    const params = new URLSearchParams({ page, limit });
    const response = await fetch(`${this.apiUrl}/api/movies?${params}`);
    return response.json();
  }

  connectWebSocket(token) {
    const ws = new WebSocket(`${this.apiUrl.replace('http', 'ws')}?token=${token}`);

    ws.onmessage = (event) => {
      const data = JSON.parse(event.data);
      if (data.type === 'progress') {
        // Handle progress updates
        console.log('Torrent progress:', data.torrents);
      }
    };

    return ws;
  }
}

// Usage
const api = new DupeAPI(API_BASE);
const torrents = await api.getTorrents();
const ws = api.connectWebSocket('your-token');

cURL Examples

# Get torrents
curl -X GET http://localhost:3001/api/torrents

# Add magnet link
curl -X POST http://localhost:3001/api/magnet \
  -H "Content-Type: application/json" \
  -d '{"magnet":"magnet:?xt=urn:btih:abc123..."}'

# Upload torrent file
curl -X POST http://localhost:3001/api/transfer \
  -F "torrent=@/path/to/file.torrent"

# Get system info
curl -X GET http://localhost:3001/api/system/info

📚 Cross-References

Project Structure - Overall architecture overview
Component Documentation - Frontend component details
Deployment Guide - Production setup instructions
WebSocket Events - Real-time event reference

Implementation Files

server/server.js - Main API implementation
client/src/utils/api.js - Frontend API client
client/src/stores/ - State management stores

This API documentation provides comprehensive coverage of all available endpoints, WebSocket events, and usage patterns. For implementation details and examples, refer to the cross-referenced files and documentation.

13 KiB Raw Blame History

du.pe - API Documentation

🔌 API Overview

📡 WebSocket Connection

Connection Endpoint

WebSocket Events

Progress Updates

File Updates

🛣️ REST API Endpoints

Torrent Management

GET /api/torrents

POST /api/transfer

POST /api/magnet

DELETE /api/torrents/:infoHash

File Streaming

GET /stream/:infoHash/:fileIndex

Media Library

GET /api/movies

GET /api/tvshows

GET /api/files

Search Functionality

GET /api/search

System Information

GET /api/system/info

GET /api/system/disk

Trash Management

GET /api/trash

POST /api/trash/:id/restore

DELETE /api/trash/:id

DELETE /api/trash

🔒 Authentication (Planned)

Token-Based Authentication

Login Endpoint (Planned)

Logout Endpoint (Planned)

📊 Error Handling

Standard Error Response Format

Common Error Codes

WebSocket Error Events

🔄 Rate Limiting

Current Limits

Planned Enhancements

🧭 Usage Examples

JavaScript/TypeScript Client

cURL Examples

📚 Cross-References

Related Documentation

Implementation Files

13 KiB

Raw Blame History