tasks-backend/API_DOCUMENTATION.md

Interview Quiz API Documentation

Quick Access

Interactive Documentation: http://localhost:3000/api-docs

OpenAPI Specification: 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

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

Login

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)

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

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

Start a Quiz (Guest User)

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

{
  "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

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

Quiz Session

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

Guest Session

{
  "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:

{
  "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:

{
  "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

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:

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

Support

For API support, contact: support@interviewquiz.com

License

MIT License