Skip to content

API.md

Latest commit

 

History

History
527 lines (392 loc) · 8.08 KB

API.md

File metadata and controls

527 lines (392 loc) · 8.08 KB

StreamRank API Reference

Complete API documentation for the StreamRank video recommendation platform.

Base URL: http://localhost:8080/api

Authentication

Most endpoints require authentication via JWT token from Supabase Auth.

Include the token in request headers:

Authorization: Bearer <your-jwt-token>

Feed Endpoints

Get Personalized Feed

Retrieves personalized video recommendations for a user.

GET /feed/{userId}

Parameters

Name Type In Description
userId UUID path User's unique identifier
limit integer query Max videos to return (default: 20)

Response 200 OK

{
  "videos": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Beautiful Nature Documentary",
      "videoUrl": "https://videos.pexels.com/...",
      "thumbnailUrl": "https://images.pexels.com/...",
      "durationSec": 45,
      "likeCount": 150,
      "viewCount": 1200,
      "tags": ["nature", "wildlife", "documentary"],
      "creator": {
        "id": "user-uuid",
        "username": "naturelover"
      }
    }
  ],
  "hasMore": true
}

Get Cold-Start Feed

Retrieves recommendations for users without interaction history.

GET /feed/cold-start

Parameters

Name Type In Description
limit integer query Max videos to return (default: 20)

Response 200 OK

Same format as personalized feed.

Get Debug Feed

Retrieves recommendations with full score breakdown for debugging.

GET /feed/{userId}/debug

Parameters

Name Type In Description
userId UUID path User's unique identifier
limit integer query Max videos to return (default: 10)

Response 200 OK

{
  "videos": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Beautiful Nature Documentary",
      "scores": {
        "total": 0.785,
        "contentAffinity": 0.82,
        "collaborative": 0.65,
        "popularity": 0.71,
        "recency": 0.89,
        "watchTime": 0.55,
        "exploration": 0.1
      }
    }
  ],
  "hasMore": false
}

Interaction Endpoints

Log Interaction

Records a user interaction with a video.

POST /interactions

Request Body

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "videoId": "660e8400-e29b-41d4-a716-446655440001",
  "eventType": "LIKE",
  "watchDuration": 30
}

Event Types

Type Description Weight
VIEW User viewed the video +0.1
LIKE User liked the video +1.0
UNLIKE User removed like -0.5
SKIP User skipped the video -0.3
COMPLETE User watched to completion +0.5
SHARE User shared the video +1.5

Response 201 Created

{
  "id": "interaction-uuid",
  "userId": "user-uuid",
  "videoId": "video-uuid",
  "eventType": "like",
  "watchDuration": 30,
  "createdAt": "2024-12-12T10:30:00Z"
}

Get User Interaction History

Retrieves recent interactions for a user.

GET /interactions/user/{userId}

Parameters

Name Type In Description
userId UUID path User's unique identifier
limit integer query Max interactions to return (default: 50)

Response 200 OK

{
  "interactions": [
    {
      "id": "interaction-uuid",
      "videoId": "video-uuid",
      "eventType": "like",
      "watchDuration": 30,
      "createdAt": "2024-12-12T10:30:00Z"
    }
  ]
}

Get User Stats

Retrieves aggregated interaction statistics for a user.

GET /interactions/user/{userId}/stats

Response 200 OK

{
  "totalInteractions": 150,
  "likes": 45,
  "skips": 20,
  "completions": 85
}

Get User Liked Videos

Retrieves IDs of videos the user has liked.

GET /interactions/user/{userId}/liked

Response 200 OK

{
  "likedVideoIds": [
    "video-uuid-1",
    "video-uuid-2"
  ]
}

User Endpoints

Create User

Creates a new user in the system.

POST /users

Request Body

{
  "id": "supabase-auth-uuid",
  "username": "johndoe",
  "email": "john@example.com"
}

Response 201 Created

{
  "id": "user-uuid",
  "username": "johndoe",
  "email": "john@example.com",
  "createdAt": "2024-12-12T10:00:00Z"
}

Get User

Retrieves user information.

GET /users/{id}

Response 200 OK

{
  "id": "user-uuid",
  "username": "johndoe",
  "email": "john@example.com",
  "createdAt": "2024-12-12T10:00:00Z",
  "lastActiveAt": "2024-12-12T15:30:00Z"
}

Get User Preferences

Retrieves a user's tag preferences.

GET /users/{id}/preferences

Response 200 OK

{
  "preferences": [
    {
      "tag": "nature",
      "affinityScore": 0.85,
      "interactionCount": 25,
      "lastUpdated": "2024-12-12T15:00:00Z"
    },
    {
      "tag": "cooking",
      "affinityScore": -0.3,
      "interactionCount": 5,
      "lastUpdated": "2024-12-11T10:00:00Z"
    }
  ]
}

Metrics Endpoints

Get User Metrics

Retrieves recommendation quality metrics for a user.

GET /metrics/user/{userId}

Response 200 OK

{
  "precisionAt10": 0.7,
  "recallAt10": 0.45,
  "ndcgAt10": 0.68,
  "ctr": 0.35,
  "likeRate": 0.28,
  "skipRate": 0.15,
  "avgWatchPercentage": 0.72
}

Get System Metrics

Retrieves system-wide aggregate metrics.

GET /metrics/system

Response 200 OK

{
  "totalUsers": 1500,
  "totalVideos": 500,
  "totalInteractions": 45000,
  "avgPrecisionAt10": 0.65,
  "avgNdcgAt10": 0.62,
  "systemCtr": 0.32,
  "avgSessionDuration": 420
}

Get Feed Diversity

Analyzes diversity of a user's current feed.

GET /metrics/user/{userId}/diversity

Response 200 OK

{
  "diversityScore": 0.73,
  "tagDistribution": {
    "nature": 4,
    "cooking": 3,
    "sports": 2,
    "music": 1
  },
  "durationDistribution": {
    "short": 3,
    "medium": 5,
    "long": 2
  },
  "videoCount": 10
}

Get Collaborative Insights

Retrieves collaborative filtering insights for a user.

GET /metrics/user/{userId}/collaborative

Response 200 OK

{
  "isViable": true,
  "similarUsers": [
    {
      "userId": "similar-user-uuid",
      "similarity": 0.85
    }
  ],
  "cacheStats": {
    "cacheSize": 150,
    "uniqueUserPairs": 75
  }
}

Admin Endpoints

Seed Videos

Imports videos from Pexels API into the database.

POST /admin/seed

Parameters

Name Type In Description
count integer query Number of videos to import (default: 10)
query string query Search query for Pexels (default: "nature")

Response 200 OK

{
  "message": "Successfully seeded 10 videos",
  "videosAdded": 10
}

Error Responses

All endpoints may return the following error responses:

400 Bad Request

{
  "error": "Bad Request",
  "message": "Invalid user ID format",
  "timestamp": "2024-12-12T10:30:00Z"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired token",
  "timestamp": "2024-12-12T10:30:00Z"
}

404 Not Found

{
  "error": "Not Found",
  "message": "User not found: {userId}",
  "timestamp": "2024-12-12T10:30:00Z"
}

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred",
  "timestamp": "2024-12-12T10:30:00Z"
}

Rate Limiting

Currently no rate limiting is implemented for local development. In production, consider implementing:

  • 100 requests/minute for feed endpoints
  • 50 requests/minute for interaction endpoints
  • 10 requests/minute for admin endpoints

Changelog

Version Date Changes
1.0.0 2024-12-12 Initial API release with collaborative filtering