Skip to content

API‐Documentation

Jump to bottom
Karthik K Pradeep edited this page Oct 4, 2025 · 1 revision

API Documentation

VisionGrade provides a comprehensive REST API for all system operations. This documentation covers all available endpoints, authentication, and usage examples.

🔐 Authentication

JWT Token Authentication

All API requests (except public endpoints) require a valid JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Login Endpoint

POST /api/auth/login
Content-Type: application/json

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

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "email": "user@example.com",
      "role": "student",
      "firstName": "John",
      "lastName": "Doe"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

👤 User Management

Get Current User

GET /api/auth/me
Authorization: Bearer <token>

Update Profile

PUT /api/users/profile
Authorization: Bearer <token>
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890"
}

Change Password

PUT /api/auth/change-password
Authorization: Bearer <token>
Content-Type: application/json

{
  "currentPassword": "oldpassword",
  "newPassword": "newpassword123"
}

🎓 Student Endpoints

Get Student Dashboard

GET /api/students/dashboard
Authorization: Bearer <student-token>

Response:

{
  "success": true,
  "data": {
    "student": {
      "id": 1,
      "rollNumber": "CS2021001",
      "semester": 6,
      "cgpa": 8.5
    },
    "recentMarks": [...],
    "attendance": {
      "overall": 85.5,
      "subjects": [...]
    },
    "predictions": {
      "universityExam": 78.5,
      "confidence": 0.85
    }
  }
}

Get Marks

GET /api/students/marks?semester=6&subject=CS301
Authorization: Bearer <student-token>

Get Attendance

GET /api/students/attendance?month=2025-01
Authorization: Bearer <student-token>

Get Performance Predictions

GET /api/students/predictions
Authorization: Bearer <student-token>

👨‍🏫 Faculty Endpoints

Get Faculty Dashboard

GET /api/faculty/dashboard
Authorization: Bearer <faculty-token>

Get Assigned Classes

GET /api/faculty/classes
Authorization: Bearer <faculty-token>

Add Student Marks

POST /api/faculty/marks
Authorization: Bearer <faculty-token>
Content-Type: application/json

{
  "studentId": 1,
  "subjectId": 1,
  "examType": "internal",
  "marks": 85,
  "maxMarks": 100,
  "examDate": "2025-01-15"
}

Mark Attendance

POST /api/faculty/attendance
Authorization: Bearer <faculty-token>
Content-Type: application/json

{
  "classId": 1,
  "date": "2025-01-15",
  "students": [
    { "studentId": 1, "status": "present" },
    { "studentId": 2, "status": "absent" }
  ]
}

Get Class Performance

GET /api/faculty/classes/1/performance
Authorization: Bearer <faculty-token>

👨‍💼 Admin Endpoints

Get System Statistics

GET /api/admin/stats
Authorization: Bearer <admin-token>

Response:

{
  "success": true,
  "data": {
    "totalStudents": 1250,
    "totalFaculty": 85,
    "totalSubjects": 45,
    "activeUsers": 892,
    "systemHealth": "good"
  }
}

Create User

POST /api/admin/users
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "email": "newuser@example.com",
  "password": "temppassword123",
  "role": "student",
  "firstName": "Jane",
  "lastName": "Smith",
  "rollNumber": "CS2025001"
}

Get All Users

GET /api/admin/users?page=1&limit=20&role=student
Authorization: Bearer <admin-token>

Update User

PUT /api/admin/users/1
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "firstName": "Updated Name",
  "isActive": true
}

Delete User

DELETE /api/admin/users/1
Authorization: Bearer <admin-token>

📚 Academic Data

Subjects

# Get all subjects
GET /api/subjects

# Get subject by ID
GET /api/subjects/1

# Create subject (Admin only)
POST /api/admin/subjects
{
  "name": "Data Structures",
  "code": "CS301",
  "credits": 4,
  "semester": 3
}

Classes

# Get classes
GET /api/classes?semester=6

# Create class (Admin only)
POST /api/admin/classes
{
  "name": "CS301-A",
  "subjectId": 1,
  "facultyId": 2,
  "semester": 6,
  "section": "A"
}

🤖 ML Service Integration

Get Predictions

GET /api/ml/predictions/student/1
Authorization: Bearer <token>

Trigger Model Training

POST /api/admin/ml/train
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "modelType": "performance_prediction",
  "dataRange": {
    "startDate": "2024-01-01",
    "endDate": "2024-12-31"
  }
}

Get Model Status

GET /api/admin/ml/models/status
Authorization: Bearer <admin-token>

📊 Reports

Generate Student Report

POST /api/reports/student
Authorization: Bearer <token>
Content-Type: application/json

{
  "studentId": 1,
  "semester": 6,
  "format": "pdf",
  "includeAttendance": true,
  "includePredictions": true
}

Generate Class Report

POST /api/reports/class
Authorization: Bearer <faculty-token>
Content-Type: application/json

{
  "classId": 1,
  "reportType": "performance",
  "format": "pdf"
}

🔔 Notifications

Get Notifications

GET /api/notifications?page=1&limit=10
Authorization: Bearer <token>

Mark as Read

PUT /api/notifications/1/read
Authorization: Bearer <token>

Send Notification (Admin/Faculty)

POST /api/notifications
Authorization: Bearer <token>
Content-Type: application/json

{
  "recipientId": 1,
  "type": "warning",
  "title": "Low Attendance Alert",
  "message": "Your attendance is below 75%"
}

📁 File Upload

Upload Profile Picture

POST /api/upload/profile
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <image-file>

Upload Document

POST /api/upload/document
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <document-file>
type: assignment|report|certificate

🔍 Search & Filtering

Search Students

GET /api/search/students?q=john&semester=6&section=A
Authorization: Bearer <token>

Search Faculty

GET /api/search/faculty?q=smith&department=CS
Authorization: Bearer <admin-token>

📈 Analytics

Get Performance Analytics

GET /api/analytics/performance?period=semester&semester=6
Authorization: Bearer <token>

Get Attendance Analytics

GET /api/analytics/attendance?period=month&month=2025-01
Authorization: Bearer <token>

⚠️ Error Responses

All API endpoints return consistent error responses:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "email": "Email is required",
      "password": "Password must be at least 8 characters"
    }
  }
}

Common Error Codes

  • UNAUTHORIZED (401): Invalid or missing token
  • FORBIDDEN (403): Insufficient permissions
  • NOT_FOUND (404): Resource not found
  • VALIDATION_ERROR (400): Invalid input data
  • INTERNAL_ERROR (500): Server error

🔄 Rate Limiting

API endpoints are rate-limited to prevent abuse:

  • General endpoints: 1000 requests per 15 minutes
  • Authentication endpoints: 200 requests per 15 minutes
  • File upload endpoints: 50 requests per 15 minutes

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

🧪 Testing the API

Using cURL

# Login
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@visiongrade.com","password":"Admin@123"}'

# Get dashboard (replace TOKEN with actual token)
curl -X GET http://localhost:5000/api/students/dashboard \
  -H "Authorization: Bearer TOKEN"

Using Postman

  1. Import the API collection (if available)
  2. Set up environment variables for base URL and tokens
  3. Use the authentication endpoint to get tokens
  4. Test other endpoints with the obtained tokens

📚 Additional Resources

Clone this wiki locally