QuizLab API Documentation

---

Overview

The QuizLab application provides a RESTful API for managing educational entities such as users, departments, academic terms, classes, quizzes, questions, attempts, and performance tracking. All endpoints are prefixed with /api/v1 and are protected by Laravel Sanctum token authentication.

---

Core Entities

Entity	Table	Key Fields
User	users	id, name, email, role (admin, hr, teacher, student)
Department	departments	id, name
AcademicTerm	academic_terms	id, name, start_date, end_date
SchoolClass	classes	id, name, department_id, term_id, teacher_id, enrollment_code
Quiz	quizzes	id, title, type, status, class_id, time_limit_minutes, passing_score, max_attempts
Question	questions	id, quiz_id, type, points, content
Attempt	attempts	id, quiz_id, user_id, status, score_obtained, score_total

---

Authentication Flow

1. Register – POST /auth/register (admin/HR only)
2. Login – POST /auth/login returns a Sanctum token.
3. Token Storage – The token is stored in Postman collection variables and sent as Authorization: Bearer <token> on every request.
4. Logout – POST /auth/logout revokes the token.

---

API Endpoints

Auth

• POST /auth/register – Create a new user (admin/HR).
• POST /auth/login – Authenticate and receive token.
• POST /auth/logout – Revoke token.
• GET /auth/me – Retrieve authenticated user profile.
• PUT /auth/profile – Update profile fields.

User Management (admin & HR)

• GET /users – List all users.
• POST /users – Create user.
• GET /users/{id} – View user.
• PUT /users/{id} – Update user.
• DELETE /users/{id} – Delete user.

Department

• GET /departments
• POST /departments
• GET /departments/{id}
• PUT /departments/{id}
• DELETE /departments/{id}

Academic Term

• GET /academic-terms
• POST /academic-terms
• GET /academic-terms/{id}
• PUT /academic-terms/{id}
• DELETE /academic-terms/{id}

Class Management

• GET /classes
• POST /classes
• GET /classes/{id}
• PUT /classes/{id}
• POST /classes/{id}/enroll – Enroll a single student.
• POST /classes/{id}/enroll-bulk – Enroll multiple students.

Quiz Management

• GET /quizzes
• POST /quizzes
• GET /quizzes/{id}
• PUT /quizzes/{id} – Update quiz attributes.
• PATCH /quizzes/{id}/publish – Change status to published.
• POST /quizzes/{id}/questions – Add a question (payload requires type, points, content).
• DELETE /quizzes/{id}/questions/{questionId} – Remove a question.

Attempt Flow

• GET /quizzes/{quizId}/attempts – List attempts for current user.
• POST /quizzes/{quizId}/attempts – Start a new attempt.
• GET /attempts/{attemptId} – View attempt details.
• POST /attempts/{attemptId}/answers – Submit answer (payload: question_id, answer_content).
• POST /attempts/{attemptId}/submit – Finalise attempt and calculate score.

Dashboard & Reporting

• GET /dashboard/admin – Global statistics (users, departments, classes, quizzes).
• GET /dashboard/teacher – Teacher‑specific stats (classes, quizzes, recent attempts).
• GET /dashboard/student – Student‑specific stats (enrolled classes, upcoming quizzes, recent results).
• GET /dashboard/leaderboard – Top performers across the system.
• GET /dashboard/class/{classId}/performance – Detailed per‑class performance for teachers/admin/HR.
• GET /dashboard/student/credits – Aggregate credit summary for a student.

---

Flowchart (Mermaid)

flowchart TD
    %% Define styles
    classDef admin fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef hr fill:#FFD580,stroke:#333,stroke-width:2px;
    classDef teacher fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef student fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef entity fill:#F0E68C,stroke:#333,stroke-width:2px;

    %% Users
    A[Admin]:::admin -->|manage| U[User]:::entity
    H[HR]:::hr -->|manage| U
    T[Teacher]:::teacher -->|create/manage| C[Class]:::entity
    S[Student]:::student -->|enroll in| C

    %% Entities hierarchy
    C --> D[Department]:::entity
    C --> Tm[AcademicTerm]:::entity
    C --> Q[Quiz]:::entity
    Q --> Qn[Question]:::entity
    S --> Atn[Attempt]:::entity
    Atn --> Ans[Answer]:::entity

    %% Dashboard routes
    subgraph Dashboard
        DAdmin[Admin Stats]:::admin
        DTeacher[Teacher Stats]:::teacher
        DStudent[Student Stats]:::student
        DClassPerf[Class Performance]:::teacher
        DStudentCred[Student Credits]:::student
    end
    A --> DAdmin
    T --> DTeacher
    S --> DStudent
    T --> DClassPerf
    S --> DStudentCred

    %% API flow arrows
    U -->|auth token| Auth[Auth Service]
    Auth -->|token| A
    Auth -->|token| H
    Auth -->|token| T
    Auth -->|token| S

Loading

---

Postman Collection

The QuizLab_postman.json file contains a fully configured Postman collection that mirrors the API endpoints listed above. It includes:

• Environment variables for base_url and token.
• Pre‑request scripts that automatically capture the login token and set it for subsequent requests.
• Folder‑level authentication for each role (Admin, HR, Teacher, Student).
• Example request bodies for creating departments, terms, classes, quizzes, questions, and attempts.

---

Usage Guide

1. Import the QuizLab_postman.json collection into Postman.
2. Set the base_url variable to the running Laravel server (e.g., http://127.0.0.1:8000/api/v1).
3. Run the Auth > Login request for the desired user role. The token will be stored automatically.
4. Execute the folder corresponding to the role to test CRUD operations and workflow scenarios.
5. Review the Dashboard endpoints to verify reporting data after performing quiz attempts.

---

Development & Testing

• Run migrations with php artisan migrate:fresh --seed to initialise the database.
• Use php artisan serve to start the development server.
• Execute the Postman collection via Newman for automated regression testing.

---

Contributing

• Follow PSR‑12 coding standards.
• Add new API routes in routes/api.php and corresponding controller methods.
• Update the Postman collection and this README whenever new endpoints are introduced.

---

End of documentation