# Quiz System API - Postman Documentation

## Overview
This documentation provides instructions for setting up and using the Quiz System API in Postman. The API allows customers to take quizzes, track progress, and receive detailed scores and analytics.

## Setup Instructions

### 1. Import the Collection
1. Download the Postman collection file: `QuizSystem.postman_collection.json`
2. Open Postman
3. Click "Import" in the top left
4. Drag and drop the collection file or browse to its location
5. Click "Import" to confirm

### 2. Set Up Environment Variables
Create a new environment with the following variables:

| Variable | Initial Value | Description |
|----------|---------------|-------------|
| `base_url` | `http://localhost:8000/api/v1` | Base URL for API requests |
| `token` | (empty) | Authentication token |
| `quiz_id` | (empty) | Current quiz ID |
| `customer_quiz_id` | (empty) | Current customer quiz session ID |

### 3. Authentication
1. Use the "Login" request to obtain an authentication token
2. The token will be automatically set in the `token` environment variable
3. All subsequent requests will use this token for authentication

## Collection Structure

The collection is organized into the following folders:

### Authentication
- **Login**: Authenticates a user and stores the token
- **Register**: Creates a new user account
- **Logout**: Invalidates the current token

### Quizzes
- **List Quizzes**: Get a list of all available quizzes
- **Show Quiz Details**: Get detailed information about a specific quiz
- **Show Quiz with Questions**: Get a quiz with all its questions and answers

### Quiz Sessions
- **Start Quiz**: Create a new quiz session or retrieve an ongoing one
- **Get Quiz Status**: Check the status of an in-progress quiz
- **Submit Answer**: Submit an answer for a question
- **Mark Question as Difficult**: Mark a question for later review
- **Track Time**: Update time spent on a question
- **Complete Quiz**: Finish a quiz session and calculate final score
- **Get Quiz Results**: Retrieve detailed results for a completed quiz
- **Get Answer Explanation**: View explanations for a specific question
- **Get Quiz History**: View customer's quiz history
- **Get Quiz Rankings**: View leaderboard for a specific quiz
- **Get Category Rankings**: View leaderboard for a specific category

## Request Examples

### Start a Quiz Session

```
POST {{base_url}}/quizzes/{{quiz_id}}/start
Authorization: Bearer {{token}}
```

Response will include the session ID, which is automatically stored in the `customer_quiz_id` variable for subsequent requests.

### Submit an Answer

```
POST {{base_url}}/customer-quizzes/{{customer_quiz_id}}/answer
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "question_id": 1,
  "selected_answer_id": 3,
  "time_spent": 45
}
```

### Get Quiz Results

```
GET {{base_url}}/customer-quizzes/{{customer_quiz_id}}/results
Authorization: Bearer {{token}}
```

## Test Scripts

The collection includes pre-request scripts and test scripts to:

1. Set environment variables automatically
2. Validate responses
3. Ensure the workflow between requests works correctly

Example test script (for Start Quiz):

```javascript
// Store the customer_quiz_id for future requests
pm.test("Store session ID", function() {
    var jsonData = pm.response.json();
    if (jsonData.data && jsonData.data.session_id) {
        pm.environment.set("customer_quiz_id", jsonData.data.session_id);
    }
});
```

## Running the Collection as a Flow

You can run the collection as a complete flow to simulate a user taking a quiz:

1. List Quizzes
2. Show Quiz Details
3. Start Quiz
4. Submit Answers for multiple questions
5. Complete Quiz
6. Get Quiz Results

Use the Collection Runner to execute this flow with different data sets.

## Troubleshooting

### Common Issues

1. **Authentication Errors (401)**
   - Ensure you've run the Login request
   - Check that the token is correctly set in environment variables

2. **Resource Not Found (404)**
   - Verify the IDs being used (quiz_id, customer_quiz_id)
   - Ensure the resources exist in your database

3. **Validation Errors (422)**
   - Check the request body format
   - Ensure all required fields are included

### Getting Help

If you encounter any issues not covered in this documentation, please contact the API development team at support@quizsystem.com.