Skip to content

Latest commit

 

History

History
1138 lines (966 loc) · 23.6 KB

api-documentation.md

File metadata and controls

1138 lines (966 loc) · 23.6 KB

🚀 IIIT Social - Comprehensive API Documentation

Version: 1.0.0
Base URL: https://your-supabase-project.supabase.co/rest/v1
Authentication: Bearer Token (JWT from Supabase Auth)

📋 Table of Contents

  1. Project Overview
  2. Authentication
  3. Data Models
  4. Core APIs
  5. Real-time Features
  6. Error Handling
  7. Rate Limiting
  8. Webhooks

🎯 Project Overview

IIIT Social is a comprehensive campus social platform featuring:

  • Dual Identity System: Public and Anonymous personas
  • Smart Team Formation: AI-powered matching using vector embeddings
  • Campus Marketplace: Gig economy for students
  • Event Discovery: Unified event feed with squad formation
  • Anonymous Boards: Safe space for discussions
  • Real-time Messaging: Direct communication channels

Core Architecture

  • Backend: Supabase (PostgreSQL + Auth + Storage + Edge Functions)
  • AI/ML: Vector embeddings for semantic matching
  • Real-time: Supabase Realtime for live updates
  • Storage: File storage for avatars and resumes

🔐 Authentication

Auth Endpoints

Register User

POST /auth/v1/signup
Content-Type: application/json

{
  "email": "student@iiit.ac.in",
  "password": "securePassword123",
  "data": {
    "full_name": "John Doe",
    "student_id": "2021101001"
  }
}

Login

POST /auth/v1/token?grant_type=password
Content-Type: application/json

{
  "email": "student@iiit.ac.in",
  "password": "securePassword123"
}

Refresh Token

POST /auth/v1/token?grant_type=refresh_token
Content-Type: application/json

{
  "refresh_token": "your_refresh_token"
}

Headers for Authenticated Requests

Authorization: Bearer <your_jwt_token>
apikey: <your_supabase_anon_key>
Content-Type: application/json

📊 Data Models

User Profiles

Public Profile

interface PublicProfile {
  id: string;                    // UUID
  user_id: string;              // FK to auth.users
  full_name: string;
  avatar_url?: string;
  resume_text?: string;
  skills_vector?: number[];      // AI-generated embeddings
  academic_goals: {
    [course_id: string]: string;  // Flexible personality description
  };
  social_battery: string;        // Flexible personality description
  github_url?: string;
  linkedin_url?: string;
  reputation_score: number;
  created_at: string;
  updated_at: string;
}

Anonymous Profile

interface AnonProfile {
  id: string;
  user_id: string;              // FK to auth.users
  handle: string;               // e.g., "Quantum Potato"
  avatar_seed: string;          // For generated avatars
  karma: number;
  created_at: string;
}

Marketplace

Market Item

interface MarketItem {
  id: string;
  creator_id: string;           // FK to public_profiles
  type: 'food_run' | 'study_help' | 'survey' | 'skill_trade';
  title: string;
  description: string;
  reward: string;
  location?: string;
  deadline?: string;
  status: 'open' | 'claimed' | 'completed' | 'cancelled';
  claimer_id?: string;          // FK to public_profiles
  max_participants?: number;
  current_participants: number;
  tags: string[];
  created_at: string;
  updated_at: string;
}

Team Matching

Match Request

interface MatchRequest {
  id: string;
  user_id: string;
  context: string;              // e.g., "CS101_Project", "Hackathon_2024", "event_buddy"
  course_code?: string;         // e.g., "CS101", "MATH202"
  event_name?: string;          // e.g., "Hackathon 2024", "Cultural Fest"
  role_needed?: string;
  min_commitment: 'low' | 'medium' | 'high';
  skills_required: string[];
  description: string;
  deadline?: string;
  requirements_embedding?: number[];
  status: 'active' | 'matched' | 'cancelled';
  created_at: string;
}

Match Result

interface MatchResult {
  user: PublicProfile;
  match_score: number;          // 0-100
  compatibility_factors: {
    academic_alignment: number;
    skill_overlap: number;
    commitment_match: number;
    social_compatibility: number;
  };
  reason: string;
}

Events

Event

interface Event {
  id: string;
  title: string;
  description: string;
  event_type: 'academic' | 'cultural' | 'sports' | 'hackathon' | 'workshop';
  organizer: string;
  location: string;
  start_time: string;
  end_time: string;
  max_attendees?: number;
  current_attendees: number;
  tags: string[];
  image_url?: string;
  external_link?: string;
  status: 'upcoming' | 'ongoing' | 'completed' | 'cancelled';
  created_at: string;
}

Anonymous Boards

Anonymous Post

interface AnonymousPost {
  id: string;
  author_id: string;            // FK to anon_profiles
  board: string;                // e.g., "confessions", "course_reviews"
  content: string;
  upvotes: number;
  downvotes: number;
  comment_count: number;
  tags: string[];
  is_reported: boolean;
  created_at: string;
}

Swipe Interactions

Swipe Action

interface SwipeAction {
  id: string;
  user_id: string;
  target_id: string;            // Profile, marketplace item, or match request
  target_type: 'team_match' | 'event_match' | 'marketplace';
  action: 'like' | 'pass' | 'super_like';
  created_at: string;
}

Match

interface Match {
  id: string;
  user1_id: string;
  user2_id: string;
  match_type: 'team' | 'event' | 'marketplace';
  context_id: string;           // Match request or marketplace item ID
  match_score: number;
  status: 'pending' | 'active' | 'archived';
  created_at: string;
}

Anonymous Groups

Anonymous Group

interface AnonymousGroup {
  id: string;
  name: string;
  description: string;
  group_type: 'study' | 'hobby' | 'support' | 'project' | 'general';
  avatar_seed: string;          // For generated group avatar
  is_private: boolean;
  max_members?: number;
  current_member_count: number;
  tags: string[];
  created_by: string;           // FK to anon_profiles
  created_at: string;
}

Group Member

interface GroupMember {
  id: string;
  group_id: string;
  anon_profile_id: string;
  role: 'admin' | 'moderator' | 'member';
  display_name: string;         // Can differ from main anon handle
  joined_at: string;
  last_active: string;
}

Group Message

interface GroupMessage {
  id: string;
  group_id: string;
  sender_id: string;            // FK to group_members
  content: string;
  message_type: 'text' | 'image' | 'poll';
  reply_to?: string;            // FK to another message
  upvotes: number;
  created_at: string;
}

🛠 Core APIs

1. Profile Management

Get Public Profile

GET /profiles_public?user_id=eq.{user_id}

Update Public Profile

PATCH /profiles_public?user_id=eq.{user_id}
Content-Type: application/json

{
  "full_name": "Updated Name",
  "resume_text": "Updated resume content",
  "academic_goals": {
    "CS101": "Aiming for top grades, willing to put in extra hours",
    "HSS": "Just want to pass and learn the basics"
  },
  "social_battery": "I enjoy working in small focused groups, prefer deep conversations over large gatherings"
}

Get Anonymous Profile

GET /profiles_anon?user_id=eq.{user_id}

Generate Skills Vector (Edge Function)

POST /functions/v1/generate-embedding
Content-Type: application/json

{
  "resume_text": "Software engineer with 3 years experience...",
  "academic_info": "Computer Science student, interested in AI/ML"
}

2. Marketplace APIs

Get Marketplace Feed

GET /marketplace_items?status=eq.open&order=created_at.desc

Filter by Type

GET /marketplace_items?type=eq.food_run&status=eq.open

Create Marketplace Item

POST /marketplace_items
Content-Type: application/json

{
  "type": "food_run",
  "title": "Need someone to get Tantra noodles",
  "description": "Will pay 50 INR extra for delivery",
  "reward": "50 INR tip",
  "location": "Hostel Block A",
  "deadline": "2024-01-24T18:00:00Z",
  "max_participants": 1,
  "tags": ["food", "urgent"]
}

Claim Marketplace Item

POST /rpc/claim_marketplace_item
Content-Type: application/json

{
  "item_id": "uuid-here",
  "claimer_message": "I can get this in 30 minutes"
}

Complete Marketplace Transaction

POST /rpc/complete_marketplace_item
Content-Type: application/json

{
  "item_id": "uuid-here",
  "rating": 5,
  "feedback": "Great service!"
}

3. Team Formation APIs

Create Match Request

POST /match_requests
Content-Type: application/json

{
  "context": "CS101_Assignment_3",
  "course_code": "CS101",
  "role_needed": "Backend Developer",
  "min_commitment": "medium",
  "skills_required": ["Python", "Django", "PostgreSQL"],
  "description": "Need help with database design for our project",
  "deadline": "2024-02-01T23:59:59Z"
}

Create Event Buddy Request

POST /match_requests
Content-Type: application/json

{
  "context": "event_buddy",
  "event_name": "CodeFest Hackathon 2024",
  "role_needed": "Frontend Developer",
  "min_commitment": "high",
  "skills_required": ["React", "TypeScript", "UI/UX"],
  "description": "Looking for a frontend expert to team up for the hackathon",
  "deadline": "2024-02-15T09:00:00Z"
}

Find Teammates (Edge Function)

POST /functions/v1/find-teammates
Content-Type: application/json

{
  "context": "CS101_Assignment_3",
  "skills_required": ["Python", "Django"],
  "commitment_level": "medium",
  "max_results": 10
}

Response:

{
  "matches": [
    {
      "user": {
        "id": "uuid-here",
        "full_name": "Jane Doe",
        "avatar_url": "...",
        "reputation_score": 4.8
      },
      "match_score": 92,
      "compatibility_factors": {
        "academic_alignment": 95,
        "skill_overlap": 88,
        "commitment_match": 100,
        "social_compatibility": 85
      },
      "reason": "Strong Python skills, similar commitment level, excellent past collaboration ratings"
    }
  ]
}

Accept Team Match

POST /rpc/accept_team_match
Content-Type: application/json

{
  "match_request_id": "uuid-here",
  "partner_id": "uuid-here",
  "message": "Looking forward to working together!"
}

4. Swipe-Based Discovery

Get Swipe Queue (Team Matching)

GET /rpc/get_team_swipe_queue?match_request_id=uuid-here&limit=20

Response:

{
  "candidates": [
    {
      "profile": {
        "id": "uuid-here",
        "full_name": "Jane Doe",
        "avatar_url": "...",
        "skills_vector": [...],
        "reputation_score": 4.8
      },
      "match_score": 92,
      "compatibility_factors": {
        "academic_alignment": 95,
        "skill_overlap": 88,
        "commitment_match": 100,
        "social_compatibility": 85
      },
      "preview_reason": "Strong Python skills, high collaboration rating"
    }
  ],
  "queue_position": 1,
  "total_candidates": 15
}

Get Swipe Queue (Marketplace)

GET /rpc/get_marketplace_swipe_queue?user_location=string&item_type=string&limit=20

Get Swipe Queue (Event Matching)

GET /rpc/get_event_swipe_queue?event_id=uuid-here&limit=20

Record Swipe Action

POST /swipe_actions
Content-Type: application/json

{
  "target_id": "uuid-here",
  "target_type": "team_match",
  "action": "like"
}

Get Matches (Mutual Likes)

GET /matches?user_id=eq.{user_id}&status=eq.active&order=created_at.desc

List View (Alternative to Swipe)

GET /rpc/get_team_match_list?match_request_id=uuid-here&sort_by=match_score&limit=50
GET /marketplace_items?status=eq.open&order=match_score.desc

Response includes match_score for personalized ranking based on user profile.

5. Events APIs

Get Events Feed

GET /events?status=eq.upcoming&order=start_time.asc

Filter Events

GET /events?event_type=eq.hackathon&start_time=gte.2024-01-24T00:00:00Z

Show Interest in Event

POST /event_participants
Content-Type: application/json

{
  "event_id": "uuid-here",
  "looking_for_squad": true,
  "preferred_squad_size": 4,
  "skills_offered": ["React", "Node.js"]
}

Find Event Squad

GET /rpc/find_event_squad?event_id=uuid-here&max_results=5

6. Anonymous Boards APIs

Get Board Posts

GET /anonymous_posts?board=eq.confessions&order=created_at.desc

Create Anonymous Post

POST /anonymous_posts
Content-Type: application/json

{
  "board": "course_reviews",
  "content": "CS101 midterm was unexpectedly difficult...",
  "tags": ["CS101", "midterm", "difficulty"]
}

Vote on Post

POST /rpc/vote_anonymous_post
Content-Type: application/json

{
  "post_id": "uuid-here",
  "vote_type": "upvote"  // or "downvote"
}

Report Post

POST /rpc/report_post
Content-Type: application/json

{
  "post_id": "uuid-here",
  "reason": "inappropriate_content",
  "details": "Contains offensive language"
}

7. Anonymous Groups APIs

Get Available Groups

GET /anonymous_groups?order=current_member_count.desc

Search Groups

GET /anonymous_groups?group_type=eq.study&tags=cs.{"CS101","algorithms"}

Create Anonymous Group

POST /anonymous_groups
Content-Type: application/json

{
  "name": "CS101 Study Squad",
  "description": "Anonymous study group for CS101 students to share notes and discuss concepts",
  "group_type": "study",
  "is_private": false,
  "max_members": 50,
  "tags": ["CS101", "algorithms", "study"]
}

Join Anonymous Group

POST /rpc/join_anonymous_group
Content-Type: application/json

{
  "group_id": "uuid-here",
  "display_name": "Quantum Potato"  // Can differ from main anon handle
}

Leave Group

POST /rpc/leave_anonymous_group
Content-Type: application/json

{
  "group_id": "uuid-here"
}

Get Group Messages

GET /group_messages?group_id=eq.uuid-here&order=created_at.desc&limit=50

Send Group Message

POST /group_messages
Content-Type: application/json

{
  "group_id": "uuid-here",
  "content": "Has anyone figured out question 3 on the assignment?",
  "message_type": "text"
}

Get Group Members

GET /group_members?group_id=eq.uuid-here

Promote/Demote Member (Admin only)

POST /rpc/update_group_member_role
Content-Type: application/json

{
  "group_id": "uuid-here",
  "member_id": "uuid-here",
  "new_role": "moderator"
}

8. Messaging APIs

Create Direct Message Channel

POST /rpc/create_dm_channel
Content-Type: application/json

{
  "other_user_id": "uuid-here",
  "initial_message": "Hi! Saw your marketplace post about CS help"
}

Send Message

POST /messages
Content-Type: application/json

{
  "channel_id": "uuid-here",
  "content": "When would be a good time to meet?",
  "message_type": "text"
}

Get Channel Messages

GET /messages?channel_id=eq.uuid-here&order=created_at.asc

9. Notifications

Get User Notifications

GET /notifications?user_id=eq.{user_id}&is_read=eq.false&order=created_at.desc

Notification Types

interface Notification {
  id: string;
  user_id: string;
  type: 'team_match' | 'marketplace_claim' | 'event_reminder' | 'message' | 
        'group_invite' | 'post_reply' | 'reputation_change';
  title: string;
  content: string;
  action_url?: string;
  is_read: boolean;
  created_at: string;
}

Mark Notification as Read

PATCH /notifications?id=eq.{notification_id}
Content-Type: application/json

{
  "is_read": true
}

Mark All as Read

POST /rpc/mark_all_notifications_read

10. Search & Discovery

Global Search

POST /rpc/global_search
Content-Type: application/json

{
  "query": "machine learning",
  "filters": {
    "types": ["users", "groups", "marketplace", "events"],
    "tags": ["AI", "ML"]
  },
  "limit": 20
}

Search Users by Skills

POST /rpc/search_users_by_skills
Content-Type: application/json

{
  "skills": ["React", "Node.js"],
  "min_reputation": 4.0,
  "limit": 10
}

Discover Similar Users (AI-powered)

POST /rpc/discover_similar_users
Content-Type: application/json

{
  "based_on": "skills_and_interests",
  "limit": 15
}

Trending Topics

GET /rpc/get_trending_topics?time_window=24h&limit=10

Response:

{
  "topics": [
    {
      "tag": "CS101",
      "mention_count": 47,
      "growth_rate": 2.3,
      "context": "exam_prep"
    }
  ]
}

🔄 Real-time Features

Supabase Realtime Subscriptions

Marketplace Updates

const subscription = supabase
  .channel('marketplace')
  .on('postgres_changes', {
    event: '*',
    schema: 'public',
    table: 'marketplace_items'
  }, handleMarketplaceUpdate)
  .subscribe()

New Messages

const messageSubscription = supabase
  .channel(`channel:${channelId}`)
  .on('postgres_changes', {
    event: 'INSERT',
    schema: 'public',
    table: 'messages',
    filter: `channel_id=eq.${channelId}`
  }, handleNewMessage)
  .subscribe()

Anonymous Board Activity

const boardSubscription = supabase
  .channel('anonymous_boards')
  .on('postgres_changes', {
    event: 'INSERT',
    schema: 'public',
    table: 'anonymous_posts'
  }, handleNewPost)
  .subscribe()

Group Messages

const groupSubscription = supabase
  .channel(`group:${groupId}`)
  .on('postgres_changes', {
    event: 'INSERT',
    schema: 'public',
    table: 'group_messages',
    filter: `group_id=eq.${groupId}`
  }, handleGroupMessage)
  .subscribe()

Match Notifications

const matchSubscription = supabase
  .channel(`matches:${userId}`)
  .on('postgres_changes', {
    event: 'INSERT',
    schema: 'public',
    table: 'matches',
    filter: `user1_id=eq.${userId}||user2_id=eq.${userId}`
  }, handleNewMatch)
  .subscribe()

Notifications

const notificationSubscription = supabase
  .channel(`notifications:${userId}`)
  .on('postgres_changes', {
    event: 'INSERT',
    schema: 'public',
    table: 'notifications',
    filter: `user_id=eq.${userId}`
  }, handleNotification)
  .subscribe()

🚨 Error Handling

Standard Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    },
    "timestamp": "2024-01-24T10:30:00Z",
    "request_id": "req_123456789"
  }
}

Common Error Codes

Code Status Description
UNAUTHORIZED 401 Invalid or expired token
FORBIDDEN 403 Insufficient permissions
VALIDATION_ERROR 400 Invalid input data
NOT_FOUND 404 Resource not found
CONFLICT 409 Resource already exists
RATE_LIMITED 429 Too many requests
INTERNAL_ERROR 500 Server error

Edge Function Errors

{
  "error": {
    "code": "EMBEDDING_GENERATION_FAILED",
    "message": "Failed to generate skill embeddings",
    "details": {
      "provider": "openai",
      "reason": "API quota exceeded"
    }
  }
}

⏱ Rate Limiting

Limits by Endpoint Category

Category Limit Window
Authentication 10 requests 1 minute
Profile Updates 20 requests 5 minutes
Marketplace 100 requests 1 minute
Team Matching 50 requests 5 minutes
Messaging 200 requests 1 minute
Anonymous Posts 30 requests 5 minutes

Rate Limit Headers

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

🔗 Webhooks

Marketplace Item Claimed

{
  "event": "marketplace.item.claimed",
  "data": {
    "item_id": "uuid-here",
    "creator_id": "uuid-here",
    "claimer_id": "uuid-here",
    "claimed_at": "2024-01-24T10:30:00Z"
  }
}

Team Match Found

{
  "event": "team.match.found",
  "data": {
    "match_request_id": "uuid-here",
    "requester_id": "uuid-here",
    "matched_user_id": "uuid-here",
    "match_score": 92,
    "matched_at": "2024-01-24T10:30:00Z"
  }
}

Anonymous Post Reported

{
  "event": "anonymous.post.reported",
  "data": {
    "post_id": "uuid-here",
    "reporter_id": "uuid-here",
    "reason": "inappropriate_content",
    "reported_at": "2024-01-24T10:30:00Z"
  }
}

Swipe Match Created

{
  "event": "swipe.match.created",
  "data": {
    "match_id": "uuid-here",
    "user1_id": "uuid-here",
    "user2_id": "uuid-here",
    "match_type": "team",
    "match_score": 92,
    "created_at": "2024-01-24T10:30:00Z"
  }
}

Group Created

{
  "event": "group.created",
  "data": {
    "group_id": "uuid-here",
    "name": "CS101 Study Squad",
    "group_type": "study",
    "created_by": "uuid-here",
    "created_at": "2024-01-24T10:30:00Z"
  }
}

Group Member Joined

{
  "event": "group.member.joined",
  "data": {
    "group_id": "uuid-here",
    "member_id": "uuid-here",
    "display_name": "Quantum Potato",
    "joined_at": "2024-01-24T10:30:00Z"
  }
}

🧪 Testing & Development

Mock Data Endpoints (Development Only)

Generate Test Users

POST /functions/v1/generate-test-data
Content-Type: application/json

{
  "type": "users",
  "count": 50
}

Generate Test Marketplace Items

POST /functions/v1/generate-test-data
Content-Type: application/json

{
  "type": "marketplace",
  "count": 20
}

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-24T10:30:00Z",
  "services": {
    "database": "operational",
    "auth": "operational",
    "storage": "operational",
    "edge_functions": "operational",
    "realtime": "operational"
  }
}

📖 Additional Resources

SDK & Libraries

Development Tools

Support

Last Updated: January 24, 2026
API Version: 1.0.0