Skip to content

API_CONTRACTS.md

Latest commit

 

History

History
648 lines (550 loc) · 9.9 KB

API_CONTRACTS.md

File metadata and controls

648 lines (550 loc) · 9.9 KB
Raw

API Contracts

Complete REST API specification for the Timetable Management System Backend.

Base URL

http://localhost:8000/api/v1

Authentication

All endpoints (except auth endpoints) require JWT authentication:

Authorization: Bearer <token>

Authentication Endpoints

POST /auth/login

Login and receive JWT token.

Request:

{
  "username": "admin",
  "password": "password123"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "username": "admin",
    "email": "admin@university.edu",
    "role": "admin"
  }
}

POST /auth/register

Register new user (admin only).

Request:

{
  "username": "faculty1",
  "email": "faculty1@university.edu",
  "password": "password123",
  "role": "faculty",
  "faculty_id": 5
}

Department Endpoints

GET /departments

List all departments.

Query Parameters:

  • page: Page number (default: 1)
  • page_size: Items per page (default: 20)
  • search: Search by name

Response:

{
  "count": 10,
  "next": "http://localhost:8000/api/v1/departments?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Computer Science",
      "code": "CSE",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ]
}

POST /departments

Create department (admin only).

Request:

{
  "name": "Computer Science",
  "code": "CSE"
}

GET /departments/{id}

Get department details.

PUT /departments/{id}

Update department (admin only).

DELETE /departments/{id}

Delete department (admin only).

Course Endpoints

GET /courses

List all courses.

Query Parameters:

  • department_id: Filter by department
  • page, page_size, search

Response:

{
  "count": 5,
  "results": [
    {
      "id": 1,
      "name": "Bachelor of Technology",
      "code": "B.Tech",
      "department": 1,
      "duration_years": 4
    }
  ]
}

POST /courses

Create course (admin only).

Request:

{
  "name": "Bachelor of Technology",
  "code": "B.Tech",
  "department": 1,
  "duration_years": 4
}

Subject Endpoints

GET /subjects

List all subjects.

Query Parameters:

  • course_id: Filter by course
  • department_id: Filter by department
  • requires_lab: Filter by lab requirement

Response:

{
  "count": 20,
  "results": [
    {
      "id": 1,
      "name": "Data Structures",
      "code": "CS201",
      "course": 1,
      "credits": 3,
      "requires_lab": true,
      "lab_hours_per_week": 2,
      "theory_hours_per_week": 3
    }
  ]
}

POST /subjects

Create subject (admin only).

Request:

{
  "name": "Data Structures",
  "code": "CS201",
  "course": 1,
  "credits": 3,
  "requires_lab": true,
  "lab_hours_per_week": 2,
  "theory_hours_per_week": 3
}

Faculty Endpoints

GET /faculty

List all faculty members.

Query Parameters:

  • department_id: Filter by department
  • available: Filter by availability status

Response:

{
  "count": 15,
  "results": [
    {
      "id": 1,
      "name": "Dr. John Doe",
      "employee_id": "EMP001",
      "email": "john.doe@university.edu",
      "department": 1,
      "max_hours_per_day": 6,
      "max_hours_per_week": 20,
      "availability": {
        "monday": [1, 2, 3, 4, 5, 6],
        "tuesday": [1, 2, 3, 4, 5, 6],
        "wednesday": [1, 2, 3, 4, 5, 6],
        "thursday": [1, 2, 3, 4, 5, 6],
        "friday": [1, 2, 3, 4, 5, 6]
      }
    }
  ]
}

POST /faculty

Create faculty (admin only).

Request:

{
  "name": "Dr. John Doe",
  "employee_id": "EMP001",
  "email": "john.doe@university.edu",
  "department": 1,
  "max_hours_per_day": 6,
  "max_hours_per_week": 20
}

GET /faculty/{id}/timetable

Get personal timetable for faculty.

Response:

{
  "faculty_id": 1,
  "faculty_name": "Dr. John Doe",
  "timetable": [
    {
      "day": "monday",
      "slots": [
        {
          "slot_number": 1,
          "time": "09:00-10:00",
          "subject": "Data Structures",
          "section": "CSE-A",
          "room": "Lab-101",
          "type": "lab"
        }
      ]
    }
  ]
}

PUT /faculty/{id}/availability

Update faculty availability (faculty can update own).

Request:

{
  "monday": [1, 2, 3, 4],
  "tuesday": [1, 2, 3, 4, 5, 6],
  "wednesday": [1, 2, 3, 4],
  "thursday": [1, 2, 3, 4, 5, 6],
  "friday": [1, 2, 3, 4]
}

Room Endpoints

GET /rooms

List all rooms/labs.

Query Parameters:

  • type: Filter by type (classroom/lab)
  • capacity_min: Minimum capacity
  • department_id: Filter by department

Response:

{
  "count": 25,
  "results": [
    {
      "id": 1,
      "name": "Lab-101",
      "code": "LAB101",
      "type": "lab",
      "capacity": 30,
      "department": 1,
      "equipment": ["Computers", "Projector"]
    }
  ]
}

POST /rooms

Create room (admin only).

Request:

{
  "name": "Lab-101",
  "code": "LAB101",
  "type": "lab",
  "capacity": 30,
  "department": 1,
  "equipment": ["Computers", "Projector"]
}

Section Endpoints

GET /sections

List all sections.

Query Parameters:

  • course_id: Filter by course
  • year: Filter by year

Response:

{
  "count": 12,
  "results": [
    {
      "id": 1,
      "name": "CSE-A",
      "code": "CSE-A",
      "course": 1,
      "year": 2,
      "student_count": 60
    }
  ]
}

POST /sections

Create section (admin only).

Request:

{
  "name": "CSE-A",
  "code": "CSE-A",
  "course": 1,
  "year": 2,
  "student_count": 60
}

TimeSlot Endpoints

GET /timeslots

List all time slots.

Response:

{
  "count": 6,
  "results": [
    {
      "id": 1,
      "slot_number": 1,
      "start_time": "09:00:00",
      "end_time": "10:00:00",
      "day": "monday"
    }
  ]
}

POST /timeslots

Create time slot (admin only).

Request:

{
  "slot_number": 1,
  "start_time": "09:00:00",
  "end_time": "10:00:00",
  "day": "monday"
}

Timetable Endpoints

POST /timetables/generate

Generate new timetable (admin only).

Request:

{
  "department_id": 1,
  "course_id": 1,
  "year": 2,
  "constraints": {
    "max_iterations": 1000,
    "population_size": 100,
    "mutation_rate": 0.1,
    "crossover_rate": 0.8,
    "seed": 42
  }
}

Response:

{
  "timetable_id": 1,
  "status": "generated",
  "generated_at": "2024-01-15T10:30:00Z",
  "fitness_score": 0.95,
  "conflicts": 0,
  "warnings": [
    "Faculty Dr. John Doe has 7 hours on Monday (max: 6)"
  ]
}

GET /timetables

List all timetables.

Query Parameters:

  • department_id: Filter by department
  • course_id: Filter by course
  • year: Filter by year
  • status: Filter by status (draft/published/locked)

Response:

{
  "count": 5,
  "results": [
    {
      "id": 1,
      "department": 1,
      "course": 1,
      "year": 2,
      "status": "published",
      "version": 1,
      "generated_at": "2024-01-15T10:30:00Z",
      "fitness_score": 0.95
    }
  ]
}

GET /timetables/{id}

Get timetable details.

Response:

{
  "id": 1,
  "department": 1,
  "course": 1,
  "year": 2,
  "status": "published",
  "version": 1,
  "generated_at": "2024-01-15T10:30:00Z",
  "fitness_score": 0.95,
  "entries": [
    {
      "id": 1,
      "subject": {
        "id": 1,
        "name": "Data Structures",
        "code": "CS201"
      },
      "faculty": {
        "id": 1,
        "name": "Dr. John Doe"
      },
      "room": {
        "id": 1,
        "name": "Lab-101",
        "type": "lab"
      },
      "section": {
        "id": 1,
        "name": "CSE-A"
      },
      "day": "monday",
      "slot_number": 1,
      "time": "09:00-10:00",
      "type": "lab"
    }
  ]
}

GET /timetables/{id}/grid

Get timetable in grid format for UI.

Response:

{
  "timetable_id": 1,
  "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
  "slots": [1, 2, 3, 4, 5, 6],
  "grid": {
    "monday": {
      "1": {
        "subject": "Data Structures",
        "faculty": "Dr. John Doe",
        "room": "Lab-101",
        "section": "CSE-A",
        "type": "lab"
      }
    }
  }
}

PUT /timetables/{id}/entries/{entry_id}

Update timetable entry (admin only, manual override).

Request:

{
  "subject_id": 2,
  "faculty_id": 3,
  "room_id": 5,
  "day": "tuesday",
  "slot_number": 2
}

DELETE /timetables/{id}/entries/{entry_id}

Delete timetable entry (admin only).

POST /timetables/{id}/publish

Publish timetable (admin only).

POST /timetables/{id}/lock

Lock timetable (admin only, prevents further edits).

POST /timetables/{id}/unlock

Unlock timetable (admin only).

GET /timetables/{id}/conflicts

Get conflict analysis for timetable.

Response:

{
  "hard_conflicts": [],
  "soft_conflicts": [
    {
      "type": "faculty_overload",
      "faculty_id": 1,
      "day": "monday",
      "hours": 7,
      "max_hours": 6
    }
  ]
}

GET /timetables/{id}/export

Export timetable (PDF/Excel).

Query Parameters:

  • format: pdf or excel

Student Endpoints

GET /students/{id}/timetable

Get timetable for student's section (read-only).

Response:

{
  "student_id": 1,
  "section": "CSE-A",
  "timetable": [
    {
      "day": "monday",
      "slots": [
        {
          "slot_number": 1,
          "time": "09:00-10:00",
          "subject": "Data Structures",
          "faculty": "Dr. John Doe",
          "room": "Lab-101",
          "type": "lab"
        }
      ]
    }
  ]
}

Error Responses

All endpoints return errors in this format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field_name": ["Error message"]
    }
  }
}

HTTP Status Codes:

  • 200: Success
  • 201: Created
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 500: Internal Server Error