Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
559 lines (402 loc) · 10.2 KB

API_DOCUMENTATION.md

File metadata and controls

559 lines (402 loc) · 10.2 KB
Raw

Backend API Documentation

Base URL

http://localhost:{PORT}

Authentication

Most endpoints require authentication via JWT token passed as a cookie or in headers. Protected routes are marked with 🔒.

Response Format

All responses follow this general structure:

{
  "message": "Success/Error message",
  "data": {...}, // Optional data payload
  "error": "Error details" // Only present on error
}

Authentication Routes (/auth)

POST /auth/login

Login a user with email and password.

Request Body:

{
    "email": "user@example.com",
    "password": "SecurePass123"
}

Validation:

  • email: Valid email format, trimmed
  • password: Required string

Response (200):

{
    "message": "Login successful",
    "role": "MEMBER" // or "VISITOR" if not approved
}

Response (401):

{
    "message": "Invalid credentials"
}

POST /auth/register

Register a new user with profile information and optional profile picture.

Content-Type: multipart/form-data

Form Fields:

{
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "9876543210", // or "+919876543210"
    "password": "SecurePass123",
    "bio": "Optional bio (max 500 chars)",
    "linkedin_url": "https://linkedin.com/in/johndoe",
    "github_url": "https://github.com/johndoe",
    "degree": "Computer Science",
    "specialization": "Machine Learning",
    "primary_community_name": "ML", // ML, IS, WEB, GAMES_APPS, CYBER
    "reason_for_joining": "Detailed reason (min 10 chars, max 500 chars)"
}

File Upload:

  • profilePicture: Optional image file

Validation Rules:

  • name: 1-256 chars, letters and spaces only
  • email: Valid email format
  • phone: Indian phone number (10 digits starting with 6-9) or with +91 prefix
  • password: Min 8 chars, must contain uppercase, lowercase, and number
  • bio: Max 500 chars (optional)
  • linkedin_url: Must be valid LinkedIn URL (optional)
  • github_url: Must be valid GitHub URL (optional)
  • degree: 2-100 chars
  • specialization: 2-100 chars
  • primary_community_name: One of the enum values
  • reason_for_joining: 10-500 chars

Response (201):

{
    "message": "User registered successfully"
}

POST /auth/forgot-password

Initiate password reset process.

Request Body:

{
    "email": "user@example.com"
}

Response (200):

{
    "message": "Password reset OTP sent to email"
}

POST /auth/verify-otp

Verify OTP for password reset.

Request Body:

{
    "email": "user@example.com",
    "otp": "123456"
}

Response (200):

{
    "message": "OTP verified successfully"
}

POST /auth/reset-password

Reset password after OTP verification.

Request Body:

{
    "email": "user@example.com",
    "newPassword": "NewSecurePass123",
    "otp": "123456"
}

Response (200):

{
    "message": "Password reset successfully"
}

User Routes (/users)

GET /users/:id

Get user information by ID.

URL Parameters:

  • id: User ID (string)

Response (200):

{
    "message": "User found",
    "data": {
        "_id": "user_id",
        "name": "John Doe",
        "email": "john@example.com",
        "bio": "User bio",
        "linkedin_url": "https://linkedin.com/in/johndoe",
        "github_url": "https://github.com/johndoe",
        "photo_url": "https://cloudinary.com/image.jpg",
        "degree": "Computer Science",
        "specialization": "Machine Learning",
        "status": "approved",
        "createdAt": "2025-01-01T00:00:00.000Z"
    }
}

GET /users 🔒

Get all users with optional community filtering.

Authentication Required: Yes
Roles Allowed: GLOBAL_ADMIN, COMMUNITY_ADMIN, PR_EDITOR, MEMBER

Query Parameters:

  • community: Filter by community (ML, IS, WEB, GAMES_APPS, CYBER) - optional

Example: /users?community=ML

Response (200):

{
    "message": "Users retrieved successfully",
    "data": [
        {
            "_id": "user_id",
            "name": "John Doe",
            "email": "john@example.com",
            "primary_community_name": "ML",
            "status": "approved",
            "createdAt": "2025-01-01T00:00:00.000Z"
        }
    ]
}

Me Routes (/me)

GET /me/status 🔒

Get current user's status and profile information.

Authentication Required: Yes

Response (200):

{
    "message": "User status retrieved",
    "data": {
        "_id": "user_id",
        "name": "John Doe",
        "email": "john@example.com",
        "role": "MEMBER",
        "status": "approved",
        "primary_community": "ML",
        "profile": {
            "bio": "User bio",
            "linkedin_url": "https://linkedin.com/in/johndoe",
            "github_url": "https://github.com/johndoe",
            "photo_url": "https://cloudinary.com/image.jpg",
            "degree": "Computer Science",
            "specialization": "Machine Learning"
        }
    }
}

PUT /me/profile 🔒

Update current user's profile information.

Authentication Required: Yes

Request Body:

{
    "name": "Updated Name",
    "email": "updated@example.com",
    "phone": "9876543210",
    "bio": "Updated bio",
    "linkedin_url": "https://linkedin.com/in/updated",
    "github_url": "https://github.com/updated",
    "photo_url": "https://cloudinary.com/updated-image.jpg",
    "degree": "Updated Degree",
    "specialization": "Updated Specialization"
}

Validation Rules:

  • All fields are optional
  • name: 2-100 chars, letters and spaces only
  • email: Valid email format
  • phone: Indian phone number format
  • bio: Max 500 chars
  • linkedin_url: Must be valid LinkedIn URL
  • github_url: Must be valid GitHub URL
  • photo_url: Valid URL format
  • degree: 2-100 chars
  • specialization: 2-100 chars

Response (200):

{
    "message": "Profile updated successfully",
    "data": {
        // Updated user profile data
    }
}

Admin Routes (/admin)

GET /admin/approvals 🔒

Get list of pending user approvals.

Authentication Required: Yes
Roles Allowed: GLOBAL_ADMIN, COMMUNITY_ADMIN

Query Parameters:

  • type: Type of approval (default: "member")
  • community: Filter by community (optional)
  • status: Filter by status (pending, approved, rejected) - default: "pending"

Example: /admin/approvals?community=ML&status=pending

Response (200):

{
    "message": "Approvals retrieved successfully",
    "data": [
        {
            "_id": "user_id",
            "name": "John Doe",
            "email": "john@example.com",
            "primary_community_name": "ML",
            "reason_for_joining": "I want to learn ML",
            "status": "pending",
            "createdAt": "2025-01-01T00:00:00.000Z"
        }
    ]
}

POST /admin/approvals/:id/approve 🔒

Approve a pending user.

Authentication Required: Yes
Roles Allowed: GLOBAL_ADMIN, COMMUNITY_ADMIN

URL Parameters:

  • id: User ID to approve (string)

Response (200):

{
    "message": "User approved successfully"
}

POST /admin/approvals/:id/reject 🔒

Reject a pending user with optional reason.

Authentication Required: Yes
Roles Allowed: GLOBAL_ADMIN, COMMUNITY_ADMIN

URL Parameters:

  • id: User ID to reject (string)

Request Body:

{
    "reason": "Reason for rejection (min 10 chars, max 500 chars)"
}

Validation:

  • reason: 10-500 chars (optional, default: "No reason provided")

Response (200):

{
    "message": "User rejected successfully"
}

POST /admin/register

Register a new admin user.

Content-Type: multipart/form-data

Form Fields:

{
    "name": "Admin Name",
    "email": "admin@example.com",
    "phone": "9876543210",
    "password": "SecurePass123",
    "bio": "Admin bio",
    "linkedin_url": "https://linkedin.com/in/admin",
    "github_url": "https://github.com/admin",
    "degree": "Computer Science",
    "specialization": "System Administration",
    "primary_community_name": "ML",
    "reason_for_joining": "I am admin" // default value
}

File Upload:

  • profilePicture: Optional image file

Validation: Same as user registration with default reason_for_joining

Response (201):

{
    "message": "Admin registered successfully"
}

Data Types and Enums

Community Types

  • ML - Machine Learning
  • IS - Information Security
  • WEB - Web Development
  • GAMES_APPS - Games & Apps
  • CYBER - Cybersecurity

User Roles

  • VISITOR - Unverified user
  • MEMBER - Approved member
  • PR_EDITOR - Public Relations Editor
  • COMMUNITY_ADMIN - Community Administrator
  • GLOBAL_ADMIN - Global Administrator

User Status

  • pending - Awaiting approval
  • approved - Approved and active
  • rejected - Application rejected

Error Handling

Common Error Responses

400 Bad Request:

{
    "message": "Validation error",
    "errors": [
        {
            "field": "email",
            "message": "Invalid email format"
        }
    ]
}

401 Unauthorized:

{
    "message": "Authentication required"
}

403 Forbidden:

{
    "message": "Insufficient permissions"
}

404 Not Found:

{
    "message": "Resource not found"
}

500 Internal Server Error:

{
    "message": "Internal server error"
}

Notes for Frontend Development

  1. Authentication: JWT tokens are typically set as HTTP-only cookies. Ensure your frontend can handle cookie-based authentication.

  2. File Uploads: Profile picture uploads use multipart/form-data. Use FormData for these requests.

  3. Phone Number Format: Accept both formats: 9876543210 and +919876543210.

  4. Community Filtering: Most admin endpoints support community-based filtering for community admins.

  5. Role-Based Access: Different endpoints require different user roles. Implement role checking in your frontend routing.

  6. Error Handling: All endpoints return consistent error formats. Implement centralized error handling.

  7. Validation: Client-side validation should match server-side rules to provide better UX.