root
452 lines
14 KiB
YAML
452 lines
14 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Administrator API - Al Rahma Sunday School
|
|
version: 1.0.0
|
|
description: >
|
|
REST API for administrator functionality. These endpoints mirror the admin view features
|
|
but return JSON responses for API consumers.
|
|
|
|
All endpoints require JWT authentication using a Bearer token, unless otherwise noted.
|
|
|
|
Standard response format:
|
|
|
|
```json
|
|
{
|
|
"status": "success|error",
|
|
"message": "string",
|
|
"data": {}
|
|
}
|
|
```
|
|
|
|
servers:
|
|
- url: https://alrahmaisgl.org/api/v1
|
|
|
|
security:
|
|
- BearerAuth: []
|
|
|
|
tags:
|
|
- name: Admin Dashboard
|
|
description: Summary metrics for admins
|
|
- name: Absence
|
|
description: Admin absence/time-off self-service
|
|
- name: Search
|
|
description: Tokenized search across users, students, parents, staff and emergency contacts
|
|
- name: Enrollment
|
|
description: Enrollment/withdrawal data and status updates
|
|
- name: Profiles
|
|
description: Aggregate student and parent profiles for administrator views
|
|
|
|
paths:
|
|
/administrator/dashboard:
|
|
get:
|
|
tags: [Admin Dashboard]
|
|
summary: Get dashboard metrics
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
200:
|
|
description: Metrics retrieved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AdminDashboardResponse'
|
|
401:
|
|
description: Unauthorized
|
|
|
|
/administrator/absence:
|
|
get:
|
|
tags: [Absence]
|
|
summary: Get admin absence info and allowed dates
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
200:
|
|
description: Absence info
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AbsenceInfoResponse'
|
|
post:
|
|
tags: [Absence]
|
|
summary: Submit absence days for current admin
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SubmitAbsenceRequest'
|
|
responses:
|
|
200:
|
|
description: Absence saved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SubmitAbsenceResponse'
|
|
422:
|
|
description: Validation error
|
|
|
|
/administrator/search:
|
|
get:
|
|
tags: [Search]
|
|
summary: Tokenized search across entities
|
|
description: >
|
|
Splits the query into tokens and matches them across multiple columns; phone-like tokens
|
|
also match common US formats.
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: q
|
|
in: query
|
|
required: true
|
|
schema: { type: string, example: "ahmed 4105551234" }
|
|
responses:
|
|
200:
|
|
description: Search results
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SearchResponse'
|
|
|
|
/administrator/enrollment-withdrawal/data:
|
|
get:
|
|
tags: [Enrollment]
|
|
summary: Data for the Enrollment/Withdrawal admin page
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: schoolYear
|
|
in: query
|
|
schema: { type: string, example: "2024-2025" }
|
|
responses:
|
|
200:
|
|
description: Data payload for UI
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/EnrollmentWithdrawalDataResponse'
|
|
|
|
/administrator/enrollment-withdrawal/update:
|
|
post:
|
|
tags: [Enrollment]
|
|
summary: Batch update enrollment statuses
|
|
description: >
|
|
Updates students' enrollment statuses and computes refunds when applicable.
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UpdateEnrollmentStatusesRequest'
|
|
responses:
|
|
200:
|
|
description: Update results
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UpdateEnrollmentStatusesResponse'
|
|
422:
|
|
description: Validation error
|
|
|
|
/administrator/students:
|
|
get:
|
|
tags: [Profiles]
|
|
summary: Aggregated student profiles
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
200:
|
|
description: Student profiles
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/StudentProfilesResponse'
|
|
|
|
/administrator/parents:
|
|
get:
|
|
tags: [Profiles]
|
|
summary: Parent profiles with recent invoice balances
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
200:
|
|
description: Parent profiles
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ParentProfilesResponse'
|
|
|
|
components:
|
|
securitySchemes:
|
|
BearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: >
|
|
Include your token in the Authorization header.
|
|
Example:
|
|
```
|
|
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
|
|
```
|
|
|
|
schemas:
|
|
BasicSuccess:
|
|
type: object
|
|
properties:
|
|
status: { type: string, example: "success" }
|
|
message: { type: string }
|
|
data: { nullable: true }
|
|
|
|
AdminDashboardResponse:
|
|
type: object
|
|
properties:
|
|
status: { type: string, example: "success" }
|
|
message: { type: string }
|
|
data:
|
|
type: object
|
|
properties:
|
|
counts:
|
|
type: object
|
|
properties:
|
|
students: { type: integer, example: 240 }
|
|
teachers: { type: integer, example: 36 }
|
|
teacherAssistants: { type: integer, example: 12 }
|
|
admins: { type: integer, example: 5 }
|
|
parents: { type: integer, example: 180 }
|
|
recentActivities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
login_time: { type: string, format: date-time }
|
|
email: { type: string, format: email }
|
|
meta:
|
|
type: object
|
|
properties:
|
|
schoolYear: { type: string, example: "2024-2025" }
|
|
semester: { type: string, example: "Fall" }
|
|
|
|
AbsenceInfoResponse:
|
|
type: object
|
|
properties:
|
|
status: { type: string, example: "success" }
|
|
message: { type: string }
|
|
data:
|
|
type: object
|
|
properties:
|
|
admin_name: { type: string }
|
|
semester: { type: string }
|
|
school_year: { type: string }
|
|
existing:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id: { type: integer }
|
|
user_id: { type: integer }
|
|
date: { type: string, format: date }
|
|
status: { type: string, enum: [present, absent, late] }
|
|
reason: { type: string, nullable: true }
|
|
semester: { type: string }
|
|
school_year: { type: string }
|
|
available_dates:
|
|
type: array
|
|
items: { type: string, format: date }
|
|
|
|
SubmitAbsenceRequest:
|
|
type: object
|
|
required: [dates, reason]
|
|
properties:
|
|
dates:
|
|
type: array
|
|
items: { type: string, format: date }
|
|
example: ["2025-09-14", "2025-10-05"]
|
|
reason_type:
|
|
type: string
|
|
example: vacation
|
|
reason:
|
|
type: string
|
|
example: Visiting family
|
|
|
|
SubmitAbsenceResponse:
|
|
type: object
|
|
properties:
|
|
status: { type: string, example: "success" }
|
|
message: { type: string }
|
|
data:
|
|
type: object
|
|
properties:
|
|
saved: { type: integer, example: 2 }
|
|
invalid:
|
|
type: array
|
|
items: { type: string, format: date }
|
|
saved_dates:
|
|
type: array
|
|
items: { type: string, format: date }
|
|
|
|
SearchResponse:
|
|
type: object
|
|
properties:
|
|
status: { type: string, example: "success" }
|
|
message: { type: string }
|
|
data:
|
|
type: object
|
|
properties:
|
|
users:
|
|
type: array
|
|
items: { type: object, additionalProperties: true }
|
|
students:
|
|
type: array
|
|
items: { type: object, additionalProperties: true }
|
|
parents:
|
|
type: array
|
|
items: { type: object, additionalProperties: true }
|
|
staff:
|
|
type: array
|
|
items: { type: object, additionalProperties: true }
|
|
emergency_contacts:
|
|
type: array
|
|
items: { type: object, additionalProperties: true }
|
|
total: { type: integer }
|
|
|
|
EnrollmentWithdrawalDataResponse:
|
|
type: object
|
|
properties:
|
|
status: { type: string, example: "success" }
|
|
message: { type: string }
|
|
data:
|
|
type: object
|
|
properties:
|
|
students:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: true
|
|
properties:
|
|
id: { type: integer }
|
|
student_id: { type: integer }
|
|
parent_id: { type: integer }
|
|
parent_label: { type: string }
|
|
enrollment_status: { type: string }
|
|
class_section: { type: string }
|
|
is_new: { type: integer, example: 0 }
|
|
new_student: { type: string, example: "No" }
|
|
registration_date_order: { type: string, example: "2025-09-01" }
|
|
classes:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id: { type: integer }
|
|
class_section_id: { type: integer }
|
|
class_section_name: { type: string }
|
|
school_year: { type: string, nullable: true }
|
|
semester: { type: string, nullable: true }
|
|
semester: { type: string }
|
|
school_year: { type: string }
|
|
schoolYears:
|
|
type: array
|
|
items: { type: string }
|
|
|
|
UpdateEnrollmentStatusesRequest:
|
|
type: object
|
|
required: [enrollment_status]
|
|
properties:
|
|
enrollment_status:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
enum: [
|
|
"admission under review",
|
|
"payment pending",
|
|
"enrolled",
|
|
"withdraw under review",
|
|
"refund pending",
|
|
"withdrawn",
|
|
"denied",
|
|
"waitlist"
|
|
]
|
|
example:
|
|
"101": "payment pending"
|
|
"102": "enrolled"
|
|
|
|
UpdateEnrollmentStatusesResponse:
|
|
type: object
|
|
properties:
|
|
status: { type: string, example: "success" }
|
|
message: { type: string }
|
|
data:
|
|
type: object
|
|
properties:
|
|
errors:
|
|
type: array
|
|
items: { type: string }
|
|
groupsByParentStatus:
|
|
type: object
|
|
additionalProperties:
|
|
type: object
|
|
additionalProperties:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
student_id: { type: integer }
|
|
student_name: { type: string }
|
|
|
|
StudentProfilesResponse:
|
|
type: object
|
|
properties:
|
|
status: { type: string, example: "success" }
|
|
message: { type: string }
|
|
data:
|
|
type: object
|
|
properties:
|
|
students:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: true
|
|
properties:
|
|
id: { type: integer }
|
|
firstname: { type: string }
|
|
lastname: { type: string }
|
|
parent_firstname: { type: string }
|
|
parent_lastname: { type: string }
|
|
parent_email: { type: string, format: email }
|
|
parent_phone: { type: string }
|
|
emergency_name: { type: string, nullable: true }
|
|
emergency_relationship: { type: string, nullable: true }
|
|
emergency_phone: { type: string, nullable: true }
|
|
allergies: { type: string, nullable: true }
|
|
medical_conditions: { type: string, nullable: true }
|
|
class_section_name: { type: string }
|
|
|
|
ParentProfilesResponse:
|
|
type: object
|
|
properties:
|
|
status: { type: string, example: "success" }
|
|
message: { type: string }
|
|
data:
|
|
type: object
|
|
properties:
|
|
parents:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id: { type: integer }
|
|
school_id: { type: string }
|
|
firstname: { type: string }
|
|
lastname: { type: string }
|
|
email: { type: string, format: email }
|
|
cellphone: { type: string }
|
|
gender: { type: string, nullable: true }
|
|
created_at: { type: string, format: date-time }
|
|
school_year: { type: string }
|
|
paid_amount: { type: number }
|
|
balance: { type: number }
|
|
|