add changes
This commit is contained in:
AD2025
299
API_DOCUMENTATION.md
Normal file
299
API_DOCUMENTATION.md
Normal file
@@ -0,0 +1,299 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user