300 lines
6.9 KiB
Markdown
300 lines
6.9 KiB
Markdown
# 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
|