Sql_Adv_Proj

📝 Examination System - Exams API Documentation

Overview
Base URL
API Endpoints
Stored Procedures
Error Handling
Business Rules

Overview

The Exams API provides comprehensive functionality for managing student examinations, including:

🎯 Exam Generation - Dynamically generate exams with MCQ and True/False questions
✍️ Answer Submission - Submit and auto-correct exam answers
📊 Exam Review - View detailed exam results with correct answers
📜 Exam History - Retrieve all exams taken by a student
⏱️ Status Tracking - Real-time exam status and remaining time

Base URL

http://localhost:3000/api/v1/exams

API Endpoints

Generate Exam

Generates a new exam for a student with a mix of MCQ and True/False questions.

POST /api/v1/exams/generate

Request Body:

Field	Type	Required	Default	Description
`courseId`	integer	✅	-	Course ID for which exam is generated
`studentId`	integer	✅	-	Student ID taking the exam
`mcqCount`	integer	❌	5	Number of MCQ questions (max 10 total)
`tfCount`	integer	❌	5	Number of True/False questions (auto-calculated as 10 - mcqCount)

Example Request:

{
  "courseId": 11,
  "studentId": 1,
  "mcqCount": 6,
  "tfCount": 4
}

Success Response (200):

{
  "success": true,
  "data": {
    "examDetails": {
      "Status": 1,
      "StatusMessage": "Exam generated successfully",
      "ExamID": 101,
      "StudentID": 1
    },
    "questions": [
      {
        "questionid": 1,
        "questiontext": "What is JavaScript?",
        "questiontype": "MCQ",
        "degree": 10,
        "choicelabel": "A",
        "choicetext": "A programming language"
      },
      {
        "questionid": 1,
        "questiontext": "What is JavaScript?",
        "questiontype": "MCQ",
        "degree": 10,
        "choicelabel": "B",
        "choicetext": "A markup language"
      }
    ],
    "ExamStartedAt": "2026-01-23T10:30:00.000Z"
  }
}

Error Response (500):

{
  "success": false,
  "data": "Server Error",
  "error": "Detailed error message"
}

Submit Exam Answers

Submits student answers for an exam and returns the calculated grade.

POST /api/v1/exams/submit

Request Body:

Field	Type	Required	Description
`examID`	integer	✅	Exam ID to submit answers for
`studentID`	integer	✅	Student ID submitting the answers
`answers`	string	✅	Comma-separated answer labels (e.g., “A,B,C,True,False,A,B,True,C,A”)

Example Request:

{
  "examID": 101,
  "studentID": 1,
  "answers": "A,B,C,T,F,A,B,T,C,A"
}

Success Response (200) - On Time Submission:

{
  "success": true,
  "data": {
    "message": "Answers submitted successfully",
    "grade": 85
  }
}

Success Response (200) - Time Exceeded:

{
  "success": true,
  "data": {
    "message": "Exam time exceeded. Answers submitted as no answers.",
    "grade": 0
  }
}

Error Response (400):

{
  "success": false,
  "data": [
    {
      "msg": "examID is required",
      "param": "examID",
      "location": "body"
    }
  ]
}

Error Response (500):

{
  "success": false,
  "data": {
    "message": "Server Error",
    "error": "Detailed error message"
  }
}

Get Exam Review

Retrieves detailed exam review including questions, choices, student answers, and correct answers.

GET /api/v1/exams/review/:examID/:studentID

Path Parameters:

Parameter	Type	Description
`examID`	integer	Exam ID to review
`studentID`	integer	Student ID who took the exam

Example Request:

GET /api/v1/exams/review/101/1

Success Response (200):

{
  "success": true,
  "data": [
    {
      "questionid": 1,
      "questiontext": "What is JavaScript?",
      "selectedLabel": "A",
      "correctLabel": "A",
      "mark": 10,
      "choices": [
        {
          "label": "A",
          "text": "A programming language"
        },
        {
          "label": "B",
          "text": "A markup language"
        },
        {
          "label": "C",
          "text": "A database"
        },
        {
          "label": "D",
          "text": "An operating system"
        }
      ]
    },
    {
      "questionid": 2,
      "questiontext": "JavaScript is case-sensitive.",
      "selectedLabel": "T",
      "correctLabel": "T",
      "mark": 10,
      "choices": [
        {
          "label": "T",
          "text": "T"
        },
        {
          "label": "F",
          "text": "F"
        }
      ]
    }
  ]
}

Error Response (500):

{
  "success": false,
  "error": "Detailed error message"
}

Get Student Exams History

Retrieves all exams taken by a specific student.

GET /api/v1/exams/:studentID

Path Parameters:

Parameter	Type	Description
`studentID`	integer	Student ID to get exam history for

Example Request:

GET /api/v1/exams/1

Success Response (200):

{
  "success": true,
  "data": [
    {
      "examid": 101,
      "courseid": 11,
      "coursename": "JavaScript Fundamentals",
      "grade": 85,
      "examdate": "2026-01-23T10:30:00.000Z",
      "ExamStartedAt": "2026-01-23T10:30:00.000Z"
    },
    {
      "examid": 102,
      "courseid": 12,
      "coursename": "React.js",
      "grade": 90,
      "examdate": "2026-01-22T14:00:00.000Z",
      "ExamStartedAt": "2026-01-22T14:00:00.000Z"
    }
  ]
}

Error Response (500):

{
  "success": false,
  "error": "Detailed error message"
}

Check Exam Status

Checks the current status of an ongoing exam and returns remaining time.

GET /api/v1/exams/:examId/:studentID

Path Parameters:

Parameter	Type	Description
`examId`	integer	Exam ID to check status for
`studentID`	integer	Student ID taking the exam

Example Request:

GET /api/v1/exams/101/1

Success Response (200) - Active Exam:

{
  "success": true,
  "status": "ACTIVE",
  "remainingMinutes": "12.45"
}

Error Response (400) - Already Submitted:

{
  "success": false,
  "status": "SUBMITTED",
  "message": "Exam already submitted"
}

Error Response (400) - Time Expired:

{
  "success": false,
  "status": "TIMEOUT",
  "message": "Exam time has expired"
}

Error Response (404) - Exam Not Found:

{
  "success": false,
  "message": "Exam not found"
}

Error Response (500):

{
  "success": false,
  "error": "Detailed error message"
}

Stored Procedures

The Exams API uses the following SQL Server stored procedures:

Procedure	Purpose	Parameters
`generate_exam`	Generate a new exam with random questions	`@courseId`, `@studentId`, `@mcqCount`, `@tfCount`
`getexamquestions`	Retrieve questions for a generated exam	`@examid`
`exam_answers`	Store student’s answers	`@examID`, `@studentID`, `@ans1` through `@ans10`
`exam_correction`	Calculate and store exam grade	`@examID`, `@studentID`
`GetExamReview_Split`	Get detailed exam review with answers	`@examID`, `@studentID`
`GetStudentExamsHistory`	Get all exams for a student	`@studentID`

Error Handling

HTTP Status Codes

Code	Status	Description
`200`	OK	Request successful
`400`	Bad Request	Validation error, exam already submitted, or time expired
`404`	Not Found	Exam not found
`500`	Internal Server Error	Server-side or database error

Exam Status Types

Status	Description
`ACTIVE`	Exam is currently in progress
`SUBMITTED`	Exam has already been submitted and graded
`TIMEOUT`	Exam time limit (15 minutes) has expired

Business Rules

Exam Generation

Total questions per exam: 10 questions
Default split: 5 MCQ + 5 True/False
Questions are randomly selected from the course question pool
Each exam gets a unique ExamID
ExamStartedAt timestamp is recorded for time tracking

Time Limits

Exam Duration: 15-20 minutes (configurable)
Time validation is performed on answer submission
If time exceeded, all answers are submitted as null

Answer Submission

Answers must be comma-separated string
Maximum 10 answers per exam
Missing answers are padded with null
Auto-correction runs immediately after submission
Grade is calculated and stored in the database

Exam Review

Available only after exam submission
Shows all questions with:
- Student’s selected answer
- Correct answer
- Individual question marks
- All available choices

API Quick Reference

Method	Endpoint	Description
`POST`	`/api/v1/exams/generate`	Generate new exam
`POST`	`/api/v1/exams/submit`	Submit exam answers
`GET`	`/api/v1/exams/review/:examID/:studentID`	Get exam review
`GET`	`/api/v1/exams/:studentID`	Get student’s exam history
`GET`	`/api/v1/exams/:examId/:studentID`	Check exam status

Validation Schema (To Be Implemented)

Generate Exam Schema