# Interview Quiz API Documentation

## Quick Access

**Interactive Documentation**: [http://localhost:3000/api-docs](http://localhost:3000/api-docs)

**OpenAPI Specification**: [http://localhost:3000/api-docs.json](http://localhost:3000/api-docs.json)

## Overview

This API provides comprehensive endpoints for managing an interview quiz application with support for:
- User authentication and authorization
- Guest sessions without registration
- Quiz management and session tracking
- User bookmarks and progress tracking
- Admin dashboard and user management

## API Endpoints Summary

### Authentication (4 endpoints)
- `POST /api/auth/register` - Register a new user account
- `POST /api/auth/login` - Login to user account
- `POST /api/auth/logout` - Logout user
- `GET /api/auth/verify` - Verify JWT token

### Users (3 endpoints)
- `GET /api/users/{userId}/dashboard` - Get user dashboard with statistics
- `GET /api/users/{userId}/history` - Get quiz history with pagination
- `PUT /api/users/{userId}` - Update user profile

### Bookmarks (3 endpoints)
- `GET /api/users/{userId}/bookmarks` - Get user's bookmarked questions
- `POST /api/users/{userId}/bookmarks` - Add a question to bookmarks
- `DELETE /api/users/{userId}/bookmarks/{questionId}` - Remove bookmark

### Categories (5 endpoints)
- `GET /api/categories` - Get all active categories
- `POST /api/categories` - Create new category (Admin)
- `GET /api/categories/{id}` - Get category details
- `PUT /api/categories/{id}` - Update category (Admin)
- `DELETE /api/categories/{id}` - Delete category (Admin)

### Quiz (5 endpoints)
- `POST /api/quiz/start` - Start a new quiz session
- `POST /api/quiz/submit` - Submit an answer
- `POST /api/quiz/complete` - Complete quiz session
- `GET /api/quiz/session/{sessionId}` - Get session details
- `GET /api/quiz/review/{sessionId}` - Review completed quiz

### Guest (4 endpoints)
- `POST /api/guest/start-session` - Start a guest session
- `GET /api/guest/session/{guestId}` - Get guest session details
- `GET /api/guest/quiz-limit` - Check guest quiz limit
- `POST /api/guest/convert` - Convert guest to registered user

### Admin (13 endpoints)

#### Statistics & Analytics
- `GET /api/admin/statistics` - Get system-wide statistics
- `GET /api/admin/guest-analytics` - Get guest user analytics

#### Guest Settings
- `GET /api/admin/guest-settings` - Get guest settings
- `PUT /api/admin/guest-settings` - Update guest settings

#### User Management
- `GET /api/admin/users` - Get all users with pagination
- `GET /api/admin/users/{userId}` - Get user details
- `PUT /api/admin/users/{userId}/role` - Update user role
- `PUT /api/admin/users/{userId}/activate` - Reactivate user
- `DELETE /api/admin/users/{userId}` - Deactivate user

#### Question Management
- `POST /api/admin/questions` - Create new question
- `PUT /api/admin/questions/{id}` - Update question
- `DELETE /api/admin/questions/{id}` - Delete question

## Authentication

### Bearer Token Authentication

Most endpoints require JWT authentication. Include the token in the Authorization header:

```
Authorization: Bearer <your-jwt-token>
```

### Guest Token Authentication

Guest users use a special header for authentication:

```
x-guest-token: <guest-session-uuid>
```

## Response Codes

- `200` - Success
- `201` - Created
- `400` - Bad Request / Validation Error
- `401` - Unauthorized (missing or invalid token)
- `403` - Forbidden (insufficient permissions)
- `404` - Not Found
- `409` - Conflict (duplicate resource)
- `500` - Internal Server Error

## Rate Limiting

API requests are rate-limited to prevent abuse. Default limits:
- Window: 15 minutes
- Max requests: 100 per window

## Example Usage

### Register a New User

```bash
curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "email": "john@example.com",
    "password": "password123"
  }'
```

### Login

```bash
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "password123"
  }'
```

### Start a Quiz (Authenticated User)

```bash
curl -X POST http://localhost:3000/api/quiz/start \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{
    "categoryId": 1,
    "questionCount": 10,
    "difficulty": "mixed"
  }'
```

### Start a Guest Session

```bash
curl -X POST http://localhost:3000/api/guest/start-session \
  -H "Content-Type: application/json"
```

### Start a Quiz (Guest User)

```bash
curl -X POST http://localhost:3000/api/quiz/start \
  -H "Content-Type: application/json" \
  -H "x-guest-token: <guest-session-id>" \
  -d '{
    "categoryId": 1,
    "questionCount": 5
  }'
```

## Data Models

### User
```json
{
  "id": 1,
  "username": "johndoe",
  "email": "john@example.com",
  "role": "user",
  "isActive": true,
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z"
}
```

### Category
```json
{
  "id": 1,
  "name": "JavaScript Fundamentals",
  "description": "Core JavaScript concepts",
  "questionCount": 50,
  "createdAt": "2025-01-01T00:00:00.000Z"
}
```

### Quiz Session
```json
{
  "id": 1,
  "userId": 1,
  "categoryId": 1,
  "totalQuestions": 10,
  "currentQuestionIndex": 5,
  "score": 4,
  "isCompleted": false,
  "startedAt": "2025-01-01T00:00:00.000Z"
}
```

### Guest Session
```json
{
  "guestSessionId": "550e8400-e29b-41d4-a716-446655440000",
  "convertedUserId": null,
  "expiresAt": "2025-01-02T00:00:00.000Z",
  "createdAt": "2025-01-01T00:00:00.000Z"
}
```

## Error Handling

All errors follow a consistent format:

```json
{
  "message": "Error description",
  "error": "Detailed error information (optional)"
}
```

## Pagination

Endpoints that return lists support pagination with these query parameters:

- `page` - Page number (default: 1)
- `limit` - Items per page (default: 10, max: 50)

Response includes pagination metadata:

```json
{
  "data": [...],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 50,
    "itemsPerPage": 10
  }
}
```

## Filtering and Sorting

Many endpoints support filtering and sorting:

- `sortBy` - Field to sort by (e.g., date, score, username)
- `sortOrder` - Sort direction (asc, desc)
- `category` - Filter by category ID
- `difficulty` - Filter by difficulty (easy, medium, hard)
- `role` - Filter by user role (user, admin)
- `isActive` - Filter by active status (true, false)

## Development

### Running the API

```bash
cd backend
npm install
npm start
```

### Accessing Documentation

Once the server is running, visit:
- **Swagger UI**: http://localhost:3000/api-docs
- **OpenAPI JSON**: http://localhost:3000/api-docs.json
- **Health Check**: http://localhost:3000/health

## Production Deployment

Update the server URL in `config/swagger.js`:

```javascript
servers: [
  {
    url: 'https://api.yourdomain.com/api',
    description: 'Production server'
  }
]
```

## Support

For API support, contact: support@interviewquiz.com

## License

MIT License