Skip to content

API.md

Latest commit

 

History

History
549 lines (453 loc) · 11.1 KB

API.md

File metadata and controls

549 lines (453 loc) · 11.1 KB
Raw

Films Streaming Platform API Documentation

Base URL

http://localhost:8080/api

Overview

The StreamFlix Platform provides a Netflix-level API for accessing movies and series with multiple streaming provider support, rich metadata, and blazing-fast response times through Redis caching.

Features

  • 🎬 60K+ Movies & Series with rich metadata
  • ⚡ Sub-second response times with intelligent caching
  • 🌐 5 Streaming Providers per movie/series
  • 🔍 Advanced search & filtering
  • 📊 Real-time platform statistics
  • 🔄 Automatic incremental updates

🎬 Movies Endpoints

GET /api/movies/trending

Get currently trending movies based on popularity.

Parameters:

  • limit (optional): Number of movies to return (default: 50, max: 100)
  • page (optional): Page number (default: 1)

Example:

curl "http://localhost:8080/api/movies/trending?limit=20&page=1"

Response:

{
  "success": true,
  "data": [
    {
      "_id": "tt1234567",
      "identifiers": {
        "imdb_id": "tt1234567",
        "tmdb_id": 299534
      },
      "basic_info": {
        "title": "Avengers: Endgame",
        "year": 2019,
        "type": "movie"
      },
      "ratings": {
        "tmdb": {
          "vote_average": 8.254,
          "popularity": 94.503
        }
      },
      "streaming_providers": {
        "vidsrc": {
          "url": "https://vidsrc.me/embed/movie?imdb=tt1234567",
          "status": "active"
        }
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 20
  },
  "cached": true,
  "timestamp": "2025-09-12T07:30:00.000Z"
}

GET /api/movies/new

Get recently added movies.

Parameters:

  • limit (optional): Number of movies (default: 100)
  • hours (optional): Hours back to search (default: 24)

Example:

curl "http://localhost:8080/api/movies/new?limit=50&hours=48"

GET /api/movies/:id

Get detailed information about a specific movie.

Parameters:

  • id: IMDB ID, TMDB ID, or internal ID

Example:

curl "http://localhost:8080/api/movies/tt1234567"

Response:

{
  "success": true,
  "data": {
    "_id": "tt1234567",
    "identifiers": {
      "imdb_id": "tt1234567",
      "tmdb_id": 299534
    },
    "basic_info": {
      "title": "Avengers: Endgame",
      "original_title": "Avengers: Endgame",
      "overview": "After the devastating events of Avengers: Infinity War...",
      "release_date": "2019-04-26",
      "runtime": 181
    },
    "classification": {
      "genres": [
        {"id": 28, "name": "Action"},
        {"id": 12, "name": "Adventure"}
      ]
    },
    "people": {
      "cast": [
        {
          "name": "Robert Downey Jr.",
          "character": "Tony Stark / Iron Man",
          "profile_images": {
            "w185": "https://image.tmdb.org/t/p/w185/rdj.jpg"
          }
        }
      ],
      "director": {
        "name": "Anthony Russo",
        "profile_images": {
          "w185": "https://image.tmdb.org/t/p/w185/director.jpg"
        }
      }
    },
    "images": {
      "posters": [
        {
          "urls": {
            "w500": "https://image.tmdb.org/t/p/w500/poster.jpg",
            "original": "https://image.tmdb.org/t/p/original/poster.jpg"
          }
        }
      ]
    },
    "streaming_providers": {
      "vidsrc": {
        "url": "https://vidsrc.me/embed/movie?imdb=tt1234567",
        "quality": "1080p",
        "status": "active"
      },
      "superembed": {
        "url": "https://multiembed.mov/?video_id=tt1234567",
        "quality": ["720p", "1080p"],
        "status": "active"
      }
    },
    "videos": [
      {
        "name": "Official Trailer",
        "youtube_url": "https://www.youtube.com/watch?v=hA6hldpSTF8",
        "thumbnail": "https://img.youtube.com/vi/hA6hldpSTF8/maxresdefault.jpg"
      }
    ]
  },
  "timestamp": "2025-09-12T07:30:00.000Z"
}

GET /api/movies/search

Search movies by title, cast, or other criteria.

Parameters:

  • q: Search query (title, cast, etc.)
  • genre (optional): Filter by genre
  • year (optional): Filter by year
  • rating_min (optional): Minimum rating
  • limit (optional): Results per page (default: 20)
  • page (optional): Page number (default: 1)

Example:

curl "http://localhost:8080/api/movies/search?q=avengers&genre=action&rating_min=7.0"

GET /api/movies/genres

Get all available genres.

Example:

curl "http://localhost:8080/api/movies/genres"

Response:

{
  "success": true,
  "data": [
    {
      "_id": 28,
      "name": "Action",
      "count": 8547
    },
    {
      "_id": 18,
      "name": "Drama", 
      "count": 12340
    }
  ],
  "count": 19,
  "timestamp": "2025-09-12T07:30:00.000Z"
}

GET /api/movies/genre/:genre

Get movies by specific genre.

Parameters:

  • genre: Genre name (e.g., "action", "comedy")
  • limit (optional): Results per page (default: 20)
  • page (optional): Page number
  • sort (optional): Sort by "popularity", "rating", "newest", "year"

Example:

curl "http://localhost:8080/api/movies/genre/action?sort=rating&limit=10"

GET /api/movies/:id/stream

Get streaming URLs for a specific movie.

Example:

curl "http://localhost:8080/api/movies/tt1234567/stream"

Response:

{
  "success": true,
  "data": {
    "movie_id": "tt1234567",
    "title": "Avengers: Endgame",
    "type": "movie",
    "providers": {
      "vidsrc": {
        "url": "https://vidsrc.me/embed/movie?imdb=tt1234567",
        "quality": "1080p",
        "status": "active"
      },
      "superembed": {
        "url": "https://multiembed.mov/?video_id=tt1234567",
        "quality": ["720p", "1080p"],
        "status": "active"
      },
      "twoembed": {
        "url": "https://www.2embed.cc/embed/tt1234567",
        "quality": ["720p", "1080p"],
        "status": "active"
      },
      "autoembed": {
        "url": "https://autoembed.cc/embed/movie?imdb=tt1234567",
        "quality": ["720p", "1080p"],
        "status": "active"
      },
      "smashy": {
        "url": "https://embed.smashystream.com/playere.php?imdb=tt1234567",
        "quality": ["720p", "1080p"],
        "status": "active"
      }
    },
    "total_providers": 5
  },
  "timestamp": "2025-09-12T07:30:00.000Z"
}

GET /api/movies/:id/similar

Get movies similar to the specified movie.

Parameters:

  • id: Movie IMDB ID
  • limit (optional): Number of similar movies (default: 10)

📺 Series Endpoints

GET /api/series/trending

Get trending TV series.

GET /api/series/new

Get recently added series.

GET /api/series/:id

Get detailed series information.

GET /api/series/:id/stream

Get streaming URLs for series.

Note: Series endpoints work similarly to movie endpoints but return series-specific data including seasons, episodes, and series metadata.

📊 Platform Endpoints

GET /api/stats

Get comprehensive platform statistics.

Example:

curl "http://localhost:8080/api/stats"

Response:

{
  "success": true,
  "data": {
    "content": {
      "total_movies": 47328,
      "total_series": 12847,
      "total_content": 60175,
      "added_today": 47,
      "added_this_week": 342
    },
    "providers": {
      "total_providers": 5,
      "active_providers": ["vidsrc", "superembed", "twoembed", "autoembed", "smashy"]
    },
    "top_genres": [
      {"name": "Drama", "count": 12340},
      {"name": "Comedy", "count": 9876}
    ],
    "last_updated": "2025-09-12T07:30:00.000Z"
  },
  "timestamp": "2025-09-12T07:30:00.000Z"
}

GET /api/health

Get basic health status.

GET /api/health/detailed

Get detailed health information including database and cache status.

🔄 Sync Management

GET /api/sync/status

Get current sync status and statistics.

Response:

{
  "success": true,
  "data": {
    "timestamp": "2025-09-12T07:30:00.000Z",
    "sync_running": false,
    "auto_sync_enabled": true,
    "sync_positions": {
      "movies_page": 1847,
      "series_page": 623
    },
    "last_sync": {
      "last_sync": "2025-09-12T02:00:00.000Z",
      "items_processed": 47,
      "processing_time_ms": 185000,
      "success": true
    }
  }
}

POST /api/sync/trigger

Manually trigger a sync operation.

Body:

{
  "force": false
}

💾 Cache Management

GET /api/cache/stats

Get cache performance statistics.

POST /api/cache/clear

Clear cache entries matching a pattern.

Body:

{
  "pattern": "trending:*"
}

🔍 Advanced Search

POST /api/search/advanced

Perform advanced search with multiple criteria.

Body:

{
  "title": "avengers",
  "genres": ["Action", "Adventure"],
  "years": {
    "min": 2010,
    "max": 2025
  },
  "ratings": {
    "min": 7.0,
    "max": 10.0
  },
  "cast": "Robert Downey Jr",
  "director": "Russo",
  "limit": 20,
  "page": 1,
  "sortBy": "popularity",
  "sortOrder": "desc"
}

Response Format

All API responses follow this format:

{
  "success": boolean,
  "data": object | array,
  "error": string,           // Only present if success = false
  "message": string,         // Optional descriptive message
  "pagination": object,      // For paginated results
  "cached": boolean,         // Whether response was cached
  "timestamp": string        // ISO timestamp
}

Caching

The API uses intelligent caching with different TTL values:

  • Trending content: 30 seconds
  • New content: 1 minute
  • Individual movies: 1 hour
  • Search results: 5 minutes
  • Genres: 24 hours
  • Platform stats: 5 minutes

Cache headers are included in responses:

  • X-Cache: HIT or MISS
  • X-Cache-Key: Cache key used
  • X-Cache-TTL: Time to live in seconds

Rate Limiting

  • Production: 1000 requests per 15 minutes per IP
  • Development: 10000 requests per 15 minutes per IP

Rate limit headers are included:

  • X-RateLimit-Limit: Request limit
  • X-RateLimit-Remaining: Remaining requests
  • X-RateLimit-Reset: Reset time

Error Codes

  • 200: Success
  • 400: Bad Request (invalid parameters)
  • 404: Not Found
  • 429: Too Many Requests (rate limited)
  • 500: Internal Server Error
  • 503: Service Unavailable (database/cache down)

Examples

Get Popular Action Movies

curl "http://localhost:8080/api/movies/genre/action?sort=popularity&limit=10"

Search for Marvel Movies

curl "http://localhost:8080/api/movies/search?q=marvel&rating_min=6.0"

Get Streaming URLs

curl "http://localhost:8080/api/movies/tt0848228/stream"

Check Platform Health

curl "http://localhost:8080/api/health/detailed"

Performance

The API is optimized for high performance:

  • Response Times: <500ms (cached), <2s (database)
  • Throughput: 1000+ requests/second
  • Database: MongoDB with optimized indexes
  • Cache: Redis with intelligent TTL
  • Clustering: Multi-process support

This API powers a Netflix-level streaming platform with 60K+ movies and series, providing rich metadata and multiple streaming options for each title.