# BV-SIS API Plan
## Future REST API Specification

**Document Version:** 1.0  
**Base URL:** `/api/v1`  
**Authentication:** Laravel Sanctum (Bearer token)  
**Format:** JSON  
**Versioning:** URL path versioning (`/api/v1`, `/api/v2`)

---

## 1. Authentication

### Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/auth/login` | Email/password login → token |
| POST | `/api/v1/auth/logout` | Revoke current token |
| POST | `/api/v1/auth/refresh` | Refresh token |
| GET | `/api/v1/auth/me` | Current user profile + permissions |
| POST | `/api/v1/auth/forgot-password` | Password reset request |
| POST | `/api/v1/auth/reset-password` | Reset with token |

### Token Response
```json
{
  "token": "1|abc...",
  "user": { "id": 1, "name": "...", "roles": ["registrar"] },
  "permissions": ["student.registration.view", "..."]
}
```

---

## 2. API Design Standards

### 2.1 Response Format
```json
{
  "data": {},
  "meta": { "current_page": 1, "total": 100, "per_page": 25 },
  "links": { "next": "...", "prev": "..." }
}
```

### 2.2 Error Format
```json
{
  "message": "Validation failed",
  "errors": { "email": ["The email field is required."] }
}
```

### 2.3 Conventions
- Pagination: `?page=1&per_page=25`
- Sorting: `?sort=created_at&direction=desc`
- Filtering: `?filter[status]=active&filter[faculty_id]=1`
- Search: `?search=phiri`
- Includes: `?include=faculty,programmes`
- Sparse fields: `?fields[students]=id,student_number,full_name`

---

## 3. Institution Setup Endpoints

| Method | Endpoint | Resource | Permissions |
|--------|----------|----------|-------------|
| GET | `/institution` | Institution profile | institution.setup.view |
| PUT | `/institution` | Update institution | institution.setup.configure |
| GET | `/campuses` | List campuses | institution.campuses.view |
| POST | `/campuses` | Create campus | institution.campuses.create |
| GET | `/campuses/{id}` | Show campus | institution.campuses.view |
| PUT | `/campuses/{id}` | Update campus | institution.campuses.edit |
| DELETE | `/campuses/{id}` | Delete campus | institution.campuses.delete |
| GET | `/faculties` | List faculties | institution.faculties.view |
| POST | `/faculties` | Create faculty | institution.faculties.create |
| GET | `/faculties/{id}/programs` | Programs in faculty | institution.programs.view |
| GET | `/programmes` | List programmes | institution.programmes.view |
| POST | `/programmes` | Create programme | institution.programmes.create |
| GET | `/programmes/{id}/tracks` | Programme tracks | institution.tracks.view |
| GET | `/programmes/{id}/tracks/{trackId}/structure` | Programme structure | institution.structure.view |
| POST | `/programmes/{id}/tracks/{trackId}/structure/items` | Add structure item | institution.structure.create |
| GET | `/academic-paths` | List paths | institution.paths.view |
| GET | `/academic-sessions` | List sessions | institution.sessions.view |
| POST | `/academic-sessions` | Create session | institution.sessions.create |
| GET | `/academic-intakes` | List intakes | institution.intakes.view |
| GET | `/study-period-structures` | Period structures | institution.periods.view |
| GET | `/institution/dashboard` | Dashboard stats | institution.dashboard.view |

---

## 4. Course Management Endpoints

| Method | Endpoint | Resource | Permissions |
|--------|----------|----------|-------------|
| GET | `/courses` | List courses | course.courses.view |
| POST | `/courses` | Create course | course.courses.create |
| GET | `/courses/{id}` | Show course | course.courses.view |
| PUT | `/courses/{id}` | Update course | course.courses.edit |
| DELETE | `/courses/{id}` | Delete course | course.courses.delete |
| GET | `/courses/{id}/prerequisites` | Prerequisites | course.prerequisites.view |
| POST | `/courses/{id}/prerequisites` | Add prerequisite | course.prerequisites.create |
| DELETE | `/courses/{id}/prerequisites/{prereqId}` | Remove | course.prerequisites.delete |
| GET | `/courses/{id}/managers` | Course managers | course.managers.view |
| POST | `/courses/{id}/managers` | Assign manager | course.managers.create |
| GET | `/faculties/{id}/courses` | Faculty courses | course.courses.view |

---

## 5. Student Registration Endpoints

| Method | Endpoint | Resource | Permissions |
|--------|----------|----------|-------------|
| GET | `/students` | List/search students | student.registration.view |
| POST | `/students` | Create student | student.registration.create |
| GET | `/students/{id}` | Student profile | student.registration.view |
| PUT | `/students/{id}` | Update biodata | student.registration.edit |
| GET | `/students/{id}/programs` | Student programmes | student.registration.view |
| POST | `/students/{id}/programs` | Assign programme | student.registration.edit |
| GET | `/students/{id}/courses` | Enrolled courses | student.courses.view |
| PUT | `/students/{id}/courses/{courseId}` | Update course status | student.courses.edit |
| POST | `/students/{id}/register` | Register for session | student.registration.edit |
| GET | `/students/{id}/program-structure` | View structure | student.registration.view |
| GET | `/students/{id}/documents` | List documents | student.registration.view |
| POST | `/students/{id}/documents` | Upload document | student.registration.edit |
| PUT | `/students/{id}/student-number` | Update student ID | student.id.update |
| GET | `/computer-number-schemes` | Number schemes | student.number.view |
| PUT | `/computer-number-schemes/{id}` | Update scheme | student.number.configure |
| POST | `/computer-number-schemes/generate` | Generate next number | student.number.configure |
| GET | `/online-registration-requests` | Pending requests | student.online_registration.view |
| POST | `/online-registration-requests/{id}/approve` | Approve | student.online_registration.approve |
| POST | `/online-registration-requests/{id}/reject` | Reject | student.online_registration.reject |
| GET | `/students/{id}/status` | Registration status | student.status.view |
| GET | `/students/{id}/offences` | Student offences | student.offences.view |
| POST | `/students/{id}/offences` | Record offence | student.offences.create |
| GET | `/class-lists` | Generate class list | student.classlist.view |
| GET | `/statistics/intake-vs-program` | Intake vs program stats | student.stats.view |
| GET | `/statistics/semester-vs-intake` | Semester vs intake stats | student.stats.view |
| GET | `/statistics/semester-registration` | Registration status | student.stats.view |

---

## 6. Student Admission Endpoints

| Method | Endpoint | Resource | Permissions |
|--------|----------|----------|-------------|
| GET | `/admission/settings` | Admission settings | admission.settings.view |
| PUT | `/admission/settings` | Update settings | admission.settings.configure |
| GET | `/admission/entry-requirements` | Entry requirements | admission.requirements.view |
| POST | `/admission/entry-requirements` | Create requirement | admission.requirements.create |
| GET | `/admission/templates` | Letter templates | admission.templates.view |
| POST | `/admission/templates` | Create template | admission.templates.create |
| POST | `/admission/templates/{id}/preview` | Preview letter | admission.templates.view |
| GET | `/applications` | List applications | admission.applications.view |
| POST | `/applications` | Create application | admission.applications.create |
| GET | `/applications/{id}` | Show application | admission.applications.view |
| PUT | `/applications/{id}` | Update application | admission.applications.edit |
| POST | `/applications/{id}/approve` | Approve | admission.applications.approve |
| POST | `/applications/{id}/reject` | Reject | admission.applications.reject |
| POST | `/applications/{id}/admit` | Admit → create student | admission.applications.approve |
| GET | `/admission/fees` | Registration fees | admission.fees.view |
| POST | `/admission/fees` | Create fee | admission.fees.create |
| GET | `/admission/form-templates` | Form templates | admission.forms.view |

---

## 7. Student Finance Endpoints

| Method | Endpoint | Resource | Permissions |
|--------|----------|----------|-------------|
| GET | `/fees/categories` | Fee categories | finance.fees.view |
| POST | `/fees/categories` | Create category | finance.fees.create |
| GET | `/fees` | List fees | finance.fees.view |
| POST | `/fees` | Create fee | finance.fees.create |
| POST | `/fees/assign` | Assign fee to programme/student | finance.fees.create |
| GET | `/course-fees` | Course fees | finance.coursefees.view |
| POST | `/course-fees` | Assign course fee | finance.coursefees.create |
| GET | `/invoices` | List invoices | finance.invoice.view |
| POST | `/invoices` | Create invoice | finance.invoice.create |
| GET | `/invoices/{id}` | Show invoice | finance.invoice.view |
| GET | `/invoices/{id}/pdf` | Invoice PDF | finance.invoice.print |
| GET | `/receipts` | List receipts | finance.receipts.view |
| POST | `/receipts` | Record payment | finance.receipts.create |
| GET | `/receipts/{id}/pdf` | Receipt PDF | finance.receipts.print |
| POST | `/receipts/{id}/resend` | Resend to student | finance.receipts.create |
| GET | `/students/{id}/clearance` | Student clearance | finance.clearance.view |
| PUT | `/students/{id}/clearance` | Update clearance | finance.clearance.edit |
| GET | `/minimum-payment-rules` | Payment rules | finance.minpayment.view |
| POST | `/minimum-payment-rules` | Create rule | finance.minpayment.create |
| POST | `/results/release/student/{id}` | Release student results | finance.results.release |
| POST | `/results/release/session/{sessionId}` | Release session results | finance.results.release |
| GET | `/finance/dashboard` | Finance dashboard | finance.dashboard.view |

---

## 8. Examination Endpoints

| Method | Endpoint | Resource | Permissions |
|--------|----------|----------|-------------|
| GET | `/grading-schemes` | Grading schemes | examination.config.view |
| POST | `/grading-schemes` | Create scheme | examination.config.configure |
| GET | `/exam-schedules` | Exam schedules | examination.schedule.view |
| POST | `/exam-schedules` | Create schedule | examination.schedule.create |
| GET | `/marks` | List marks | examination.marking.view |
| POST | `/marks` | Enter mark | examination.marking.create |
| PUT | `/marks/{id}` | Update mark | examination.marking.edit |
| POST | `/marks/bulk-import` | Bulk import CSV | examination.marking.create |
| POST | `/marks/{id}/moderate` | Moderate mark | examination.marking.approve |
| POST | `/marks/publish` | Publish results | examination.marking.approve |
| GET | `/students/{id}/results` | Student results | examination.results.view |
| GET | `/students/{id}/result-slip/pdf` | Result slip PDF | examination.results.print |

---

## 9. BulkSMS Endpoints

| Method | Endpoint | Resource | Permissions |
|--------|----------|----------|-------------|
| POST | `/notifications/sms/send` | Send SMS | sms.send.create |
| POST | `/notifications/email/send` | Send email | sms.send.create |
| GET | `/contact-groups` | List groups | sms.groups.view |
| POST | `/contact-groups` | Create group | sms.groups.create |
| POST | `/contact-groups/{id}/members` | Add members | sms.groups.edit |
| GET | `/message-templates` | Templates | sms.templates.view |
| POST | `/message-templates` | Create template | sms.templates.create |
| GET | `/message-logs` | Send history | sms.history.view |
| GET | `/notifications/sms/balance` | Africa's Talking balance | sms.gateway.view |

---

## 10. Student Identity Cards Endpoints

| Method | Endpoint | Resource | Permissions |
|--------|----------|----------|-------------|
| GET | `/id-cards` | List ID cards | idcard.view |
| POST | `/id-cards` | Issue ID card | idcard.create |
| GET | `/id-cards/{id}/pdf` | Card PDF | idcard.print |
| POST | `/id-cards/batch-print` | Batch print | idcard.print |
| GET | `/id-card-templates` | Templates | idcard.templates.view |
| POST | `/id-card-templates` | Create template | idcard.templates.configure |

---

## 11. System Maintenance Endpoints

| Method | Endpoint | Resource | Permissions |
|--------|----------|----------|-------------|
| GET | `/users` | List users | system.users.view |
| POST | `/users` | Create user | system.users.create |
| GET | `/roles` | List roles | system.roles.view |
| POST | `/roles` | Create role | system.roles.configure |
| GET | `/audit-logs` | Audit logs | system.audit.view |
| GET | `/system/health` | System health | system.settings.view |

---

## 12. Webhook Endpoints (Outbound)

| Event | Payload | Target |
|-------|---------|--------|
| `student.admitted` | Student data | External systems |
| `payment.received` | Receipt data | Accounting system |
| `results.released` | Student + marks | Student portal |
| `sms.delivered` | Delivery status | Internal log |

---

## 13. Rate Limiting

| Tier | Limit |
|------|-------|
| Authenticated API | 120 requests/minute |
| SMS send | 10 requests/minute |
| Bulk import | 5 requests/minute |
| Login | 5 attempts/minute |

---

## 14. API Documentation

- **Tool:** Laravel Scribe or OpenAPI 3.0 (Swagger)
- **Hosted at:** `/api/documentation`
- **Postman collection:** Auto-generated from Scribe

---

*End of API Plan*