Skip to content

API.md

Latest commit

 

History

History
569 lines (491 loc) · 9.16 KB

API.md

File metadata and controls

569 lines (491 loc) · 9.16 KB

EduGrid API Documentation

Base URL: http://localhost:8000/api/v1/
Authentication: JWT Bearer Token

🔐 Authentication

Login

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

{
  "email": "hod.cse@smslucknow.ac.in",
  "password": "HodPassword123!"
}

Response (200 OK):

{
  "access": "eyJ0eXAiOiJKV1QiLCJhbG...",
  "refresh": "eyJ0eXAiOiJKV1QiLCJhb...",
  "user": {
    "id": 1,
    "email": "hod.cse@smslucknow.ac.in",
    "name": "Dr. Rajesh Kumar",
    "role": "hod"
  }
}

Refresh Token

POST /auth/refresh/
Content-Type: application/json

{
  "refresh": "eyJ0eXAiOiJKV1QiLCJhb..."
}

Logout

POST /auth/logout/
Authorization: Bearer {access_token}

📋 Timetable Generation (Priority Queue)

1. Generate Timetable

NEW - Priority queue-based generation

POST /timetables/priority-queue/generate/
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "batch_ids": [1, 2, 3],
  "semester": 1,
  "working_days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
  "lectures_per_day": 6
}

Success Response (201 Created):

{
  "success": true,
  "timetables": [1, 2, 3],
  "constraint_report_id": 1,
  "fulfillment_percentage": 85.5
}

Failure - Pre-validation (400 Bad Request):

{
  "success": false,
  "error_type": "PRE_VALIDATION_FAILED",
  "conflicts": [
    {
      "type": "INSUFFICIENT_ROOMS",
      "severity": "CRITICAL",
      "message": "Need 3 rooms but only 2 available",
      "suggestion": "Add more classrooms or reduce batches"
    }
  ],
  "suggestions": [
    "Add more classrooms",
    "Reduce number of batches"
  ]
}

Failure - Threshold Exceeded (400 Bad Request):

{
  "success": false,
  "error_type": "THRESHOLD_EXCEEDED",
  "unfulfilled_percentage": 45.2,
  "suggestions": [
    "Add Saturday as working day",
    "Increase lectures per day to 7"
  ]
}

2. Check Feasibility

Pre-validate before generation

POST /timetables/priority-queue/check-feasibility/
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "batch_ids": [1],
  "semester": 1,
  "working_days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
  "lectures_per_day": 6
}

Response (200 OK):

{
  "feasible": true
}

or

{
  "feasible": false,
  "conflicts": [
    {
      "type": "INSUFFICIENT_TEACHERS",
      "severity": "CRITICAL",
      "message": "Need 12 teachers but only 5 available"
    }
  ]
}

3. List Timetables

GET /timetables/
Authorization: Bearer {access_token}

Response (200 OK):

[
  {
    "id": 1,
    "title": "CSE-A Semester 1",
    "batch": 1,
    "batch_name": "CSE-A",
    "status": "APPROVED",
    "is_approved": true,
    "is_active": true,
    "created_at": "2025-11-23T20:00:00Z"
  }
]

4. Get Timetable Details

GET /timetables/{id}/
Authorization: Bearer {access_token}

Response (200 OK):

{
  "timetable": {
    "id": 1,
    "title": "CSE-A Semester 1",
    "batch": 1,
    "status": "APPROVED"
  },
  "cells": [
    {
      "id": 1,
      "day": "Mon",
      "period": 1,
      "subject": 5,
      "subject_name": "Data Structures",
      "faculty": 3,
      "faculty_name": "Dr. Sharma",
      "room": 10,
      "room_code": "CR-101",
      "is_lab": false,
      "priority_level": 3
    }
  ]
}

5. Get Constraint Report

GET /timetables/{id}/constraint-report/
Authorization: Bearer {access_token}

Response (200 OK):

{
  "id": 1,
  "timetable": 1,
  "total_constraints": 100,
  "fulfilled_constraints": 85,
  "unfulfilled_constraints": 15,
  "fulfillment_percentage": 85.0,
  "passed_threshold": true,
  "special_class_conflicts": [],
  "lab_scheduling_issues": [
    {
      "subject": "Physics Lab",
      "reason": "No consecutive slots found"
    }
  ],
  "teacher_workload_violations": [],
  "room_capacity_issues": [],
  "improvement_suggestions": [
    "Consider adding Saturday as working day",
    "Increase lectures per day to 7"
  ],
  "generation_successful": true,
  "generation_duration_seconds": 2.45
}

⭐ Special Classes

1. List Special Classes

GET /timetables/special-classes/
Authorization: Bearer {access_token}

Response (200 OK):

[
  {
    "id": 1,
    "batch": 1,
    "batch_name": "CSE-A",
    "subject": 5,
    "subject_name": "Data Structures",
    "teacher": 3,
    "teacher_name": "Dr. Sharma",
    "day": "Mon",
    "lecture_number": 1,
    "room": 10,
    "room_code": "CR-101",
    "is_lab": false,
    "semester": 1,
    "notes": "Important foundation class",
    "is_active": true,
    "created_at": "2025-11-23T10:00:00Z"
  }
]

2. Create Special Class

POST /timetables/special-classes/
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "batch": 1,
  "subject": 5,
  "teacher": 3,
  "day": "Mon",
  "lecture_number": 1,
  "room": 10,
  "is_lab": false,
  "semester": 1,
  "notes": "Priority class for fundamentals"
}

Response (201 Created):

{
  "id": 1,
  "batch": 1,
  "subject": 5,
  "teacher": 3,
  "day": "Mon",
  "lecture_number": 1,
  "room": 10,
  "is_lab": false,
  "semester": 1,
  "notes": "Priority class for fundamentals",
  "is_active": true
}

3. Update Special Class

PUT /timetables/special-classes/{id}/
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "day": "Tue",
  "lecture_number": 2
}

4. Delete Special Class

DELETE /timetables/special-classes/{id}/
Authorization: Bearer {access_token}

Response (200 OK):

{
  "message": "Special class deleted"
}

👥 Batches

List Batches

GET /batches/
Authorization: Bearer {access_token}

Response:

[
  {
    "id": 1,
    "code": "CSE-A",
    "year": 1,
    "section": "A",
    "program": "B.Tech CSE",
    "department": 1,
    "course": 1
  }
]

📚 Subjects

List Subjects

GET /subjects/
Authorization: Bearer {access_token}

Response:

[
  {
    "id": 1,
    "code": "KAS101",
    "name": "Engineering Mathematics-I",
    "credits": 4,
    "is_lab": false,
    "lab_duration": 0
  },
  {
    "id": 2,
    "code": "KAS104",
    "name": "Chemistry Lab",
    "credits": 0,
    "is_lab": true,
    "lab_duration": 2
  }
]

👨‍🏫 Faculty

List Faculty

GET /faculty/
Authorization: Bearer {access_token}

Response:

[
  {
    "id": 1,
    "faculty_id": "FAC001",
    "name": "Dr. Rajesh Kumar",
    "email": "rajesh.kumar@smslucknow.ac.in",
    "department": 1,
    "designation": "Assistant Professor"
  }
]

🏫 Rooms

List Rooms

GET /rooms/
Authorization: Bearer {access_token}

Response:

[
  {
    "id": 1,
    "code": "CR-101",
    "name": "Lecture Hall 101",
    "room_type": "Lecture",
    "capacity": 60
  },
  {
    "id": 2,
    "code": "LAB-CS1",
    "name": "Computer Lab 1",
    "room_type": "Lab",
    "capacity": 30
  }
]

📖 Curriculum

List Curriculum

GET /curriculum/?semester=1
Authorization: Bearer {access_token}

Response:

[
  {
    "id": 1,
    "subject": 1,
    "subject_name": "Engineering Mathematics-I",
    "subject_code": "KAS101",
    "year": 1,
    "semester": 1,
    "is_core": true
  }
]

🎓 Teacher Portal

Get Teacher Schedule

GET /timetables/teacher/my-schedule/
Authorization: Bearer {teacher_token}

Response:

{
  "teacher": {
    "id": 1,
    "name": "Dr. Rajesh Kumar"
  },
  "schedule": [
    {
      "day": "Mon",
      "period": 1,
      "subject": "Data Structures",
      "batch": "CSE-A",
      "room": "CR-101"
    }
  ],
  "workload_stats": {
    "total_classes": 18,
    "hours_per_week": 18,
    "subjects_assigned": 2
  }
}

🔄 Error Codes

Code Description
200 Success
201 Created
400 Bad Request (validation error)
401 Unauthorized (invalid/missing token)
403 Forbidden (insufficient permissions)
404 Not Found
500 Internal Server Error

📝 Notes

Authentication

  • All endpoints (except login) require Authorization: Bearer {token} header
  • Access tokens expire in 24 hours
  • Use refresh token to get new access token

Permissions

  • HOD: Can generate timetables, manage special classes
  • Teacher: Can view own schedule only
  • Admin: Full access to all resources

Rate Limiting

  • 100 requests per minute per user
  • Reset every minute

🧪 Testing with cURL

Login

curl -X POST http://localhost:8000/api/v1/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "hod.cse@smslucknow.ac.in",
    "password": "HodPassword123!"
  }'

Generate Timetable

curl -X POST http://localhost:8000/api/v1/timetables/priority-queue/generate/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_ids": [1],
    "semester": 1,
    "working_days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
    "lectures_per_day": 6
  }'

For more details, visit the built-in API docs:

  • Swagger UI: http://localhost:8000/api/docs/
  • ReDoc: http://localhost:8000/api/redoc/