Gradebooks API

The Gradebooks module manages student grades, report cards, and academic progress.

Models

Gradebook

Main gradebook record linking student to academic period:

{
  "id": "uuid",
  "student_id": "student-uuid",
  "student": {...},
  "academic_session_id": "session-uuid",
  "semester_id": "semester-uuid",
  "class_id": "class-uuid",
  "status": "active",
  "overall_grade": "A",
  "overall_score": 92.5,
  "team_id": "team-uuid"
}

GradebookCourse

Per-course grades within a gradebook:

{
  "id": "uuid",
  "gradebook_id": "gradebook-uuid",
  "student_id": "student-uuid",
  "course_id": "course-uuid",
  "final_score": 88.5,
  "final_grade": "B+",
  "subject_id": "subject-uuid"
}

Assessment

Individual assignments/tests:

{
  "id": "uuid",
  "name": "Midterm Exam",
  "course_id": "course-uuid",
  "max_score": 100,
  "weight": 30,
  "due_date": "2024-03-15",
  "category_id": "category-uuid"
}

AssessmentResult

Student scores on assessments:

{
  "id": "uuid",
  "assessment_id": "assessment-uuid",
  "student_id": "student-uuid",
  "score": 85,
  "grade": "B",
  "submitted_at": "2024-03-14T10:00:00Z"
}

Endpoints

Gradebook CRUD

Method	Endpoint	Description
POST	`/api/gradebooks/list`	List gradebooks
GET	`/api/gradebooks/:id`	Get gradebook
POST	`/api/gradebooks`	Create gradebook
PUT	`/api/gradebooks/:id`	Update gradebook

Student Reports

Get Student Report:

GET /api/gradebooks/student/:student_id/report

Response:

{
  "student": {...},
  "academic_session": {...},
  "subjects": [
    {
      "subject": "Mathematics",
      "course_grade": "A",
      "assessments": [
        {"name": "Quiz 1", "score": 95, "max": 100},
        {"name": "Midterm", "score": 88, "max": 100}
      ]
    }
  ],
  "overall_gpa": 3.8
}

Class Summary

Get Class Summary:

GET /api/gradebooks/class/:class_id/summary

Subject Statistics

Get Subject Statistics:

GET /api/gradebooks/subject/:subject_id/statistics

Report Cards

Generate Report Card

Endpoint: POST /api/gradebooks/:id/report-card/generate

Triggers async report card generation.

Check Generation Status

Endpoint: GET /api/gradebooks/:id/report-card/status

Download Report Card

Endpoint: GET /api/gradebooks/:id/report-card

Returns PDF report card.

Assessment Results

List Results for Assessment

GET /api/assessment_results/assessment/:assessment_id

Get Statistics

GET /api/assessment_results/assessment/:assessment_id/stats

Response:

{
  "assessment": {...},
  "statistics": {
    "count": 30,
    "average": 78.5,
    "median": 80,
    "min": 45,
    "max": 98,
    "std_dev": 12.3
  }
}

Student Course Results

GET /api/assessment_results/student/:student_id/course/:course_id

Grade Calculation

Calculate Course Grade

POST /api/gradebook_courses/calculate

Recalculates grades based on assessments and weights.

Recalculate Student Grades

POST /api/gradebook_courses/student/:student_id/recalculate

Grade Scales

Define grading scales:

{
  "id": "uuid",
  "name": "Standard Scale",
  "ranges": [
    {"min": 90, "max": 100, "grade": "A", "gpa": 4.0},
    {"min": 80, "max": 89, "grade": "B", "gpa": 3.0},
    {"min": 70, "max": 79, "grade": "C", "gpa": 2.0}
  ]
}