Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
105 lines (89 loc) · 4.29 KB

API_DOCUMENTATION.md

File metadata and controls

105 lines (89 loc) · 4.29 KB
Raw

StreamFlix API Documentation

Overview

The StreamFlix API provides access to the streaming platform's backend services. It follows RESTful principles and uses JSON for data exchange.

  • Base URL: http://localhost:8080/api/v1
  • Specification: OpenAPI 3.1

Authentication

The API uses JWT (JSON Web Token) for authentication.

  1. Register: POST /auth/register
  2. Login: POST /auth/login -> Returns token
  3. Access Protected Endpoints: Add header Authorization: Bearer <token>

Endpoints

1. Authentication (/auth)

Method Endpoint Description Auth Required
POST /register Register a new user account No
POST /login Authenticate and receive JWT No
GET /verify Verify email with token No
POST /forgot-password Request password reset No
POST /reset-password Reset password with token No

2. Profiles (/profiles)

Method Endpoint Description Auth Required
GET / Get all profiles for current user Yes
POST / Create a new profile Yes
PUT /{id} Update a profile Yes
DELETE /{id} Delete a profile Yes

3. Media Content (/media)

Method Endpoint Description Auth Required
GET / Get all media (movies & series) Yes
GET /{id} Get details for specific media Yes
GET /search Search media by title Yes
GET /genre/{genre} Filter media by genre Yes

4. Movies (/media/movies)

Method Endpoint Description Auth Required
GET / Get all movies Yes
POST / Add a new movie (Admin) Yes (Admin)
PUT /{id} Update movie details (Admin) Yes (Admin)
DELETE /{id} Delete a movie (Admin) Yes (Admin)

5. Series (/media/series)

Method Endpoint Description Auth Required
GET / Get all series Yes
POST / Add a new series (Admin) Yes (Admin)
POST /{id}/seasons Add a season to series Yes (Admin)
POST /seasons/{id}/episodes Add an episode to season Yes (Admin)

6. Watchlist (/watchlist)

Method Endpoint Description Auth Required
GET / Get current profile's watchlist Yes
POST / Add item to watchlist Yes
DELETE /{mediaId} Remove item from watchlist Yes

7. Viewing Progress (/viewing-progress)

Method Endpoint Description Auth Required
GET / Get viewing history Yes
POST /start Start watching content Yes
PUT /update Update watch position Yes

8. Subscriptions (/subscriptions)

Method Endpoint Description Auth Required
GET /plans Get available subscription tiers Yes
POST /subscribe Subscribe to a plan Yes
POST /cancel Cancel current subscription Yes

9. Analytics (/analytics)

Method Endpoint Description Auth Required
GET /popular Get most popular content Yes
GET /user-stats Get viewing statistics for user Yes

10. Referrals (/referrals)

Method Endpoint Description Auth Required
POST /invite Send a referral invitation Yes
GET /status Check referral status Yes

Error Handling

The API returns standard HTTP status codes:

  • 200 OK: Success
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid input or validation error
  • 401 Unauthorized: Missing or invalid token
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 500 Internal Server Error: Server-side error

External API Integration

TMDB (The Movie Database)

  • The system integrates with TMDB to fetch metadata (posters, descriptions) for movies.
  • Service: TmdbService
  • Usage: Automatically called when adding new movies if external ID is provided.