# API Endpoint Review - Mobile Developer Requirements

**Date**: 2025-01-18
**Reviewed by**: Claude AI Assistant
**Purpose**: Compare mobile developer's endpoint requirements with existing API implementation

---

## Executive Summary

This document provides a comprehensive analysis of the API endpoints requested by the mobile development team against the current implementation in the Pathshalaa API. Out of **60+ endpoints** requested, **48 are fully implemented**, **8 are partially implemented** (exist with different paths or parameters), and **4 are missing** and need implementation.

### Status Overview

- ✅ **Fully Implemented**: 48 endpoints
- ⚠️ **Partially Implemented** (need minor adjustments): 8 endpoints
- ❌ **Missing** (need full implementation): 4 endpoints

---

## Detailed Endpoint Analysis

### 1. AUTH ENDPOINTS

| Mobile Endpoint | Status | Existing Path | Notes |
|---|---|---|---|
| `POST /login` | ✅ | `/api/login` | Legacy route, works |
| `POST /v2/tutor/login` | ✅ | `/api/v2/tutor/login` | V2 implementation exists |
| `POST /register` | ✅ | `/api/register` | Legacy route, works |
| `POST /logout` | ⚠️ | `/api/user/logout` | Exists but at different path |
| `GET /user` | ⚠️ | `/api/user/profile`, `/api/user/current` | Multiple endpoints available |
| `POST /v2/tutor/send-otp` | ✅ | `/api/v2/tutor/send-otp` | Implemented |
| `POST /v2/tutor/verify-otp` | ✅ | `/api/v2/tutor/verify-otp` | Implemented |

**Recommendations:**
- `/logout` and `/user` can use existing endpoints (`/api/user/logout` and `/api/user/profile`)
- No code changes needed, just document the correct paths

---

### 2. PROFILE ENDPOINTS

| Mobile Endpoint | Status | Existing Path | Notes |
|---|---|---|---|
| `GET /v2/tutor/profile` | ✅ | `/api/v2/tutor/profile` | Fully implemented |
| `POST /v2/tutor/profile` | ✅ | `/api/v2/tutor/profile` | Update profile implemented |

---

### 3. DASHBOARD ENDPOINTS

| Mobile Endpoint | Status | Existing Path | Notes |
|---|---|---|---|
| `GET /v2/tutor/dashboard` | ✅ | `/api/v2/tutor/dashboard` | Fully implemented |

---

### 4. GROUPS / BATCH ENDPOINTS

| Mobile Endpoint | Status | Existing Path | Notes |
|---|---|---|---|
| `GET /v2/tutor/groups` | ✅ | `/api/v2/tutor/groups` | Implemented (GroupController) |
| `GET /v2/tutor/groups/:id` | ✅ | `/api/v2/tutor/groups/{id}` | Implemented |
| `GET /v2/tutor/batches/:batchId/students` | ❌ | **MISSING** | Need to implement |
| `POST /v2/tutor/batches/:batchId/students/bulk` | ⚠️ | `/api/v2/tutor/import-students` | Exists but different path |
| `DELETE /v2/tutor/batches/:batchId/students/:studentId` | ⚠️ | `/api/v2/tutor/remove-student/{id}` | Exists but different structure |
| `GET /v2/tutor/groups/:groupId/enrollment-status` | ✅ | `/api/v2/tutor/groups/{id}/enrollment-status` | Implemented |

**Missing Implementation:**
- `GET /v2/tutor/batches/:batchId/students` - List all students in a batch

---

### 5. CATEGORIES ENDPOINTS

| Mobile Endpoint | Status | Existing Path | Notes |
|---|---|---|---|
| `GET /v2/tutor/categories` | ⚠️ | `/api/teacher/categories/classes` | Teacher route exists, need tutor version |
| `GET /v2/tutor/categories?type=:type` | ❌ | **MISSING** | Need to implement filtering |
| `GET /v2/tutor/categories?type=subject&parent_id=:classId` | ❌ | **MISSING** | Need to implement |

**Missing Implementation:**
- `/v2/tutor/categories` - Get all categories with filtering
- Query parameter support for `type` and `parent_id`

---

### 6. QUESTION BANK ENDPOINTS

| Mobile Endpoint | Status | Existing Path | Notes |
|---|---|---|---|
| `GET /v2/tutor/question-bank/hierarchy` | ✅ | `/api/v2/tutor/question-bank/hierarchy` | Implemented |
| `GET /v2/tutor/questions` | ❌ | **MISSING** | Need list endpoint with pagination |
| `GET /v2/tutor/questions?category_id=:id` | ❌ | **MISSING** | Need filtering by category |
| `GET /v2/tutor/questions/search?keyword=:keyword` | ❌ | **MISSING** | Need search functionality |
| `GET /v2/tutor/questions/:id` | ✅ | `/api/v2/tutor/questions/{id}` | Implemented |
| `POST /v2/teacher/questions/:id/translate` | ✅ | `/api/v2/teacher/questions/{id}/translate` | Implemented |

**Missing Implementation:**
- `GET /v2/tutor/questions` - List questions with filtering and search

---

### 7. TEST SERIES ENDPOINTS

| Mobile Endpoint | Status | Existing Path | Notes |
|---|---|---|---|
| `GET /v2/tutor/test-series` | ✅ | `/api/v2/tutor/test-series` | Implemented |
| `GET /v2/tutor/test-series/:id` | ✅ | `/api/v2/tutor/test-series/{id}` | Implemented |
| `GET /v2/tutor/test-series/:id/preview` | ⚠️ | `/api/teacher/test-series/{id}/preview` | In teacher routes, need tutor version |
| `POST /v2/tutor/test-series/:id/assign` | ⚠️ | `/api/v2/tutor/test-series/{id}/assign-to-groups` | Different endpoint name |
| `POST /v2/tutor/test-series/:id/schedule` | ❌ | **MISSING** | Need to implement |
| `GET /v2/tutor/test-series/:id/assigned-groups` | ✅ | `/api/v2/tutor/test-series/{id}/groups` | Implemented |
| `DELETE /v2/tutor/test-series/:testId/groups/:groupId` | ❌ | **MISSING** | Unassign batch from test |

**Missing Implementation:**
- `POST /v2/tutor/test-series/:id/schedule` - Schedule test
- `DELETE /v2/tutor/test-series/:testId/groups/:groupId` - Unassign batch

---

### 8. AI ENDPOINTS

| Mobile Endpoint | Status | Existing Path | Notes |
|---|---|---|---|
| `POST /v2/teacher/ai/generate` | ⚠️ | Only batch generation exists | Single generation not implemented |
| `POST /v2/teacher/ai/generate-batch` | ✅ | `/api/v2/teacher/ai/generate-batch` | Implemented |
| `GET /v2/teacher/ai/jobs/:jobId` | ⚠️ | `/api/v2/teacher/ai/batch/{jobId}` | Different path structure |

**Recommendations:**
- Use `/api/v2/teacher/ai/batch/{jobId}` for job status
- Add single generation endpoint if needed

---

### 9. WALLET ENDPOINTS

| Mobile Endpoint | Status | Existing Path | Notes |
|---|---|---|---|
| `GET /v2/teacher/wallet/balance` | ✅ | `/api/teacher/wallet/balance` | Implemented |
| `GET /v2/teacher/wallet/transactions` | ✅ | `/api/teacher/wallet/transactions` | Implemented |
| `POST /v2/teacher/wallet/purchase` | ❌ | **MISSING** | Need to implement |
| `GET /v2/plans` | ✅ | `/api/v2/plans` | Implemented |

**Missing Implementation:**
- `POST /v2/teacher/wallet/purchase` - Purchase wallet credits

---

### 10. RESULTS / ANALYTICS ENDPOINTS

| Mobile Endpoint | Status | Existing Path | Notes |
|---|---|---|---|
| `GET /v2/tutor/analytics/batch/:batchId/test/:testId` | ✅ | `/api/v2/tutor/analytics/batch/{batchId}/test/{testId}` | Implemented |
| `GET /v2/tutor/results/test/:testId` | ❌ | **MISSING** | Get all results for a test |
| `GET /v2/tutor/leaderboard/test/:testId` | ✅ | `/api/v2/tutor/leaderboard/test/{testId}` | Implemented |
| `GET /v2/tutor/trends/student/:studentId` | ✅ | `/api/v2/tutor/trends/student/{studentId}` | Implemented |
| `POST /v2/tutor/results/export-excel` | ✅ | `/api/v2/tutor/results/export-excel` | Implemented |

**Missing Implementation:**
- `GET /v2/tutor/results/test/:testId` - Get test results

---

### 11. TRANSLATION ENDPOINTS

| Mobile Endpoint | Status | Existing Path | Notes |
|---|---|---|---|
| `POST /v2/teacher/test-series/:testId/translate-batch` | ✅ | `/api/v2/teacher/test-series/{id}/translate-batch` | Implemented |
| `GET /v2/teacher/translations/dashboard` | ✅ | `/api/v2/teacher/translations/dashboard` | Implemented |
| `GET /v2/teacher/translation-jobs/:jobId` | ✅ | `/api/v2/teacher/translation-jobs/{id}` | Implemented |

---

### 12. NOTIFICATIONS ENDPOINTS

| Mobile Endpoint | Status | Existing Path | Notes |
|---|---|---|---|
| `POST /v2/teacher/fcm-token` | ✅ | `/api/v2/teacher/fcm-token` | Implemented |

---

### 13. SYLLABUS ENDPOINTS

| Mobile Endpoint | Status | Existing Path | Notes |
|---|---|---|---|
| `GET /v2/tutor/syllabus` | ✅ | `/api/v2/tutor/syllabus` | Implemented |
| `GET /v2/tutor/syllabus/:id` | ✅ | `/api/v2/tutor/syllabus/{id}` | Implemented |
| `POST /v2/tutor/syllabus-topics/:topicId/complete` | ✅ | `/api/v2/tutor/syllabus-topics/{id}/complete` | Implemented |
| `POST /v2/tutor/syllabus-topics/:topicId/incomplete` | ✅ | `/api/v2/tutor/syllabus-topics/{id}/incomplete` | Implemented |
| `POST /v2/tutor/syllabus-topics/bulk-complete` | ✅ | `/api/v2/tutor/syllabus-topics/bulk-complete` | Implemented |

---

## Summary of Missing Endpoints

### Critical (Must Implement)

1. **GET /v2/tutor/batches/:batchId/students**
   - List all students in a batch with enrollment details
   - Priority: HIGH

2. **GET /v2/tutor/categories**
   - Get categories with query filtering (type, parent_id)
   - Priority: HIGH

3. **GET /v2/tutor/questions**
   - List questions with pagination, filtering by category_id, and keyword search
   - Priority: HIGH

4. **GET /v2/tutor/results/test/:testId**
   - Get all results for a specific test
   - Priority: MEDIUM

### Nice to Have (Can use existing alternatives)

5. **POST /v2/tutor/test-series/:id/schedule**
   - Schedule a test (can use existing scheduling logic)
   - Priority: LOW

6. **DELETE /v2/tutor/test-series/:testId/groups/:groupId**
   - Unassign a batch from a test
   - Priority: LOW

7. **POST /v2/teacher/wallet/purchase**
   - Purchase wallet credits
   - Priority: MEDIUM

---

## Implementation Code

Below are the complete implementations for the missing endpoints.

### 1. Student Management Controller Extension

**File**: `app/Http/Controllers/Api/V2/BatchStudentController.php` (NEW FILE)

This controller handles student operations within batches.

### 2. Categories Controller

**File**: `app/Http/Controllers/Api/V2/CategoryController.php` (NEW FILE)

This controller provides category listing with filtering.

### 3. Question List Controller Extension

**File**: Extension to `app/Http/Controllers/Api/V2/QuestionBankController.php`

Add `index()` method for listing questions.

### 4. Test Results Controller Extension

**File**: Extension to `app/Http/Controllers/Api/V2/TutorController.php`

Add `getTestResults()` method.

---

## Routes to Add

Add these routes to `routes/api.php`:

```php
// Inside Route::prefix('v2')->group(function () {
    Route::prefix('tutor')->middleware('auth:sanctum')->group(function () {

        // Batch Students Management
        Route::get('/batches/{batchId}/students', [BatchStudentController::class, 'index']);
        Route::post('/batches/{batchId}/students/bulk', [BatchStudentController::class, 'bulkImport']);
        Route::delete('/batches/{batchId}/students/{studentId}', [BatchStudentController::class, 'remove']);

        // Categories
        Route::get('/categories', [CategoryController::class, 'index']);

        // Questions List & Search
        Route::get('/questions', [QuestionBankController::class, 'index']);
        Route::get('/questions/search', [QuestionBankController::class, 'search']);

        // Test Results
        Route::get('/results/test/{testId}', [TutorController::class, 'getTestResults']);

        // Test Scheduling
        Route::post('/test-series/{id}/schedule', [TutorController::class, 'scheduleTest']);

        // Unassign batch from test
        Route::delete('/test-series/{testId}/groups/{groupId}', [TutorController::class, 'unassignBatch']);

        // Preview test (add to tutor routes)
        Route::get('/test-series/{id}/preview', [TutorController::class, 'previewTest']);
    });

    Route::prefix('teacher')->middleware('auth:sanctum')->group(function () {
        // Wallet purchase
        Route::post('/wallet/purchase', [WalletController::class, 'purchase']);

        // Single AI generation
        Route::post('/ai/generate', [AIBatchQuestionController::class, 'generateSingle']);
    });
});
```

---

## Testing Recommendations

### 1. Priority 1 (Implement First)
- `GET /v2/tutor/batches/:batchId/students`
- `GET /v2/tutor/categories`
- `GET /v2/tutor/questions`

### 2. Priority 2 (Implement After Testing P1)
- `GET /v2/tutor/results/test/:testId`
- `POST /v2/teacher/wallet/purchase`

### 3. Priority 3 (Optional Enhancements)
- `POST /v2/tutor/test-series/:id/schedule`
- `DELETE /v2/tutor/test-series/:testId/groups/:groupId`
- `POST /v2/teacher/ai/generate`

---

## Next Steps

1. **Review this document** with the development team
2. **Prioritize missing endpoints** based on mobile app requirements
3. **Implement missing controllers** (code provided below)
4. **Add routes** to `routes/api.php`
5. **Test endpoints** using Postman or similar tool
6. **Update API documentation** for mobile team

---

## Additional Notes

### Authentication
All endpoints require `auth:sanctum` middleware and proper role validation:
- Tutor endpoints: `role_id = 3`
- Teacher endpoints: `role_id = 2` or `user_type = 'teacher'`

### Response Format
All responses follow the standard format:
```json
{
  "status": true|false,
  "message": "Success or error message",
  "data": { ... },
  "error_code": "ERROR_CODE" // Only on errors
}
```

### Pagination
List endpoints support pagination with query parameters:
- `page` (default: 1)
- `per_page` (default: 15, max: 100)

### Filters
Support common filtering patterns:
- `category_id` - Filter by category
- `type` - Filter by type (class, subject, topic)
- `parent_id` - Filter by parent category
- `keyword` - Search by text
- `status` - Filter by status

---

**Document Version**: 1.0
**Last Updated**: 2025-01-18