root
840 lines
23 KiB
YAML
840 lines
23 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: Parent API - Al Rahma Sunday School
|
||
version: 1.1.0
|
||
description: >
|
||
REST API for parent-related functionality in the Al Rahma Sunday School system.
|
||
All endpoints require JWT authentication using a Bearer token, unless otherwise noted.
|
||
Each response follows the standard format:
|
||
|
||
```json
|
||
{
|
||
"status": "success|error",
|
||
"message": "string",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
servers:
|
||
- url: https://alrahmaisgl.org/api/v1
|
||
|
||
security:
|
||
- BearerAuth: []
|
||
|
||
tags:
|
||
- name: Parents
|
||
description: Manage parent profiles and accounts
|
||
- name: Students
|
||
description: Access and manage parent’s student data
|
||
- name: Attendance
|
||
description: View attendance history for a parent's children
|
||
- name: Enrollment
|
||
description: Manage enrollments and student registration
|
||
- name: Payments
|
||
description: Retrieve invoices and payment details
|
||
- name: Events
|
||
description: Manage student participation in school events
|
||
|
||
paths:
|
||
/parents:
|
||
get:
|
||
tags: [Parents]
|
||
summary: List all parents (admin use)
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: page
|
||
in: query
|
||
schema: { type: integer, example: 1 }
|
||
- name: per_page
|
||
in: query
|
||
schema: { type: integer, example: 20 }
|
||
responses:
|
||
200:
|
||
description: Paginated list of parents
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/PaginatedParentsResponse'
|
||
401:
|
||
description: Unauthorized
|
||
|
||
/parents/{id}:
|
||
get:
|
||
tags: [Parents]
|
||
summary: Get parent details by ID
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
responses:
|
||
200:
|
||
description: Parent details
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Parent'
|
||
404:
|
||
description: Parent not found
|
||
401:
|
||
description: Unauthorized
|
||
|
||
/parents/{id}/profile:
|
||
get:
|
||
tags: [Parents]
|
||
summary: Get parent profile
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
responses:
|
||
200:
|
||
description: Parent profile details
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Parent'
|
||
put:
|
||
tags: [Parents]
|
||
summary: Update parent profile
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ParentUpdateRequest'
|
||
responses:
|
||
200:
|
||
description: Profile updated successfully
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/BasicSuccess'
|
||
|
||
/parents/{id}/students:
|
||
get:
|
||
tags: [Students]
|
||
summary: Get all students for a parent
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
responses:
|
||
200:
|
||
description: Student list with details
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/StudentsResponse'
|
||
post:
|
||
tags: [Students]
|
||
summary: Register a new student for this parent
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CreateStudentRequest'
|
||
responses:
|
||
200:
|
||
description: Student created
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/BasicSuccess'
|
||
|
||
/parents/{id}/students/{studentId}:
|
||
put:
|
||
tags: [Students]
|
||
summary: Update a student's info
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
- name: studentId
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/UpdateStudentRequest'
|
||
responses:
|
||
200:
|
||
description: Student updated
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/BasicSuccess'
|
||
delete:
|
||
tags: [Students]
|
||
summary: Delete a student
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
- name: studentId
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
responses:
|
||
200:
|
||
description: Student deleted
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/BasicSuccess'
|
||
|
||
/parents/{id}/attendance:
|
||
get:
|
||
tags: [Attendance]
|
||
summary: Get student attendance records
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
- name: school_year
|
||
in: query
|
||
schema: { type: string, example: "2024-2025" }
|
||
responses:
|
||
200:
|
||
description: Attendance records retrieved
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AttendanceList'
|
||
examples:
|
||
sample:
|
||
value:
|
||
status: success
|
||
message: Attendance data retrieved successfully
|
||
data:
|
||
- firstname: Ali
|
||
lastname: Ahmad
|
||
date: "2024-10-06"
|
||
status: present
|
||
reason: null
|
||
- firstname: Aisha
|
||
lastname: Ahmad
|
||
date: "2024-10-13"
|
||
status: absent
|
||
reason: Sick
|
||
|
||
/parents/{id}/payments:
|
||
get:
|
||
tags: [Payments]
|
||
summary: Retrieve invoices/payments for parent
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
responses:
|
||
200:
|
||
description: Payment history
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/InvoiceList'
|
||
examples:
|
||
sample:
|
||
value:
|
||
status: success
|
||
message: Payments retrieved successfully
|
||
data:
|
||
- id: 101
|
||
invoice_number: INV-2025-0001
|
||
parent_id: 55
|
||
amount: 550
|
||
status: unpaid
|
||
created_at: "2025-08-20 12:00:00"
|
||
|
||
/parents/{id}/enrollments:
|
||
get:
|
||
tags: [Enrollment]
|
||
summary: Get enrollment data for parent’s students
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
- name: school_year
|
||
in: query
|
||
schema: { type: string, example: "2024-2025" }
|
||
responses:
|
||
200:
|
||
description: Enrollment info
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnrollmentResponse'
|
||
|
||
/parents/{id}/enroll-classes:
|
||
get:
|
||
tags: [Enrollment]
|
||
summary: Get data for the enroll classes page
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
- name: school_year
|
||
in: query
|
||
schema: { type: string, example: "2024-2025" }
|
||
responses:
|
||
200:
|
||
description: Enroll classes data
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ParentEnrollClassesData'
|
||
post:
|
||
tags: [Enrollment]
|
||
summary: Update enrollments (enroll/withdraw)
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/UpdateParentEnrollmentsRequest'
|
||
responses:
|
||
200:
|
||
description: Enrollment updates processed
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/UpdateParentEnrollmentsResponse'
|
||
|
||
/parents/{id}/emergency-contacts:
|
||
get:
|
||
tags: [Parents]
|
||
summary: List emergency contacts for parent
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
responses:
|
||
200:
|
||
description: Emergency contacts
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EmergencyContactsList'
|
||
post:
|
||
tags: [Parents]
|
||
summary: Create or update an emergency contact
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/SaveEmergencyContactRequest'
|
||
responses:
|
||
200:
|
||
description: Saved
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/BasicSuccess'
|
||
|
||
/parents/{id}/authorized-users:
|
||
get:
|
||
tags: [Parents]
|
||
summary: List authorized users (second parents/guardians)
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
responses:
|
||
200:
|
||
description: Authorized users
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AuthorizedUsersList'
|
||
post:
|
||
tags: [Parents]
|
||
summary: Add an authorized user (pending)
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AddAuthorizedUserRequest'
|
||
responses:
|
||
200:
|
||
description: Created
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/BasicSuccess'
|
||
|
||
/parents/{id}/enroll:
|
||
post:
|
||
tags: [Enrollment]
|
||
summary: Enroll one or more students
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
student_ids:
|
||
type: array
|
||
items: { type: integer }
|
||
example: [5, 6]
|
||
responses:
|
||
200:
|
||
description: Enrollment submitted successfully
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/BasicSuccess'
|
||
|
||
/parents/{id}/events:
|
||
get:
|
||
tags: [Events]
|
||
summary: Get events and participation data
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
responses:
|
||
200:
|
||
description: Events and participation data
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EventParticipationResponse'
|
||
examples:
|
||
sample:
|
||
value:
|
||
status: success
|
||
message: Event participation data retrieved
|
||
data:
|
||
events:
|
||
- id: 1
|
||
name: Field Trip
|
||
amount: 25
|
||
start_date: "2025-10-20"
|
||
end_date: "2025-10-20"
|
||
charges:
|
||
"12:1":
|
||
student_id: 12
|
||
event_id: 1
|
||
participation: yes
|
||
charged: 25
|
||
date: "2025-09-30 10:00:00"
|
||
|
||
/parents/{id}/events/update:
|
||
post:
|
||
tags: [Events]
|
||
summary: Update student event participation
|
||
security:
|
||
- BearerAuth: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: { type: integer }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
participation:
|
||
type: object
|
||
example:
|
||
"3:1": "yes"
|
||
"3:2": "no"
|
||
responses:
|
||
200:
|
||
description: Participation updated successfully
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/BasicSuccess'
|
||
|
||
components:
|
||
securitySchemes:
|
||
BearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: JWT
|
||
description: >
|
||
Enter your JSON Web Token here.
|
||
Example:
|
||
```
|
||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
|
||
```
|
||
|
||
schemas:
|
||
BasicSuccess:
|
||
type: object
|
||
properties:
|
||
status: { type: string, example: "success" }
|
||
message: { type: string, example: "Operation completed successfully" }
|
||
data: { nullable: true }
|
||
|
||
Parent:
|
||
type: object
|
||
properties:
|
||
id: { type: integer }
|
||
firstname: { type: string }
|
||
lastname: { type: string }
|
||
email: { type: string, format: email }
|
||
cellphone: { type: string }
|
||
address_street: { type: string }
|
||
city: { type: string }
|
||
state: { type: string }
|
||
zip: { type: string }
|
||
|
||
ParentUpdateRequest:
|
||
type: object
|
||
properties:
|
||
firstname: { type: string }
|
||
lastname: { type: string }
|
||
cellphone: { type: string }
|
||
address_street: { type: string }
|
||
city: { type: string }
|
||
state: { type: string }
|
||
zip: { type: string }
|
||
|
||
PaginatedParentsResponse:
|
||
type: object
|
||
properties:
|
||
status: { type: string, example: "success" }
|
||
message: { type: string }
|
||
data:
|
||
type: object
|
||
properties:
|
||
page: { type: integer }
|
||
per_page: { type: integer }
|
||
total: { type: integer }
|
||
data:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/Parent'
|
||
|
||
StudentsResponse:
|
||
type: object
|
||
properties:
|
||
status: { type: string }
|
||
message: { type: string }
|
||
data:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id: { type: integer }
|
||
firstname: { type: string }
|
||
lastname: { type: string }
|
||
gender: { type: string }
|
||
dob: { type: string }
|
||
current_class:
|
||
type: object
|
||
properties:
|
||
class_name: { type: string }
|
||
section_name: { type: string }
|
||
medical_conditions:
|
||
type: array
|
||
items: { type: string }
|
||
allergies:
|
||
type: array
|
||
items: { type: string }
|
||
|
||
AttendanceList:
|
||
type: object
|
||
properties:
|
||
status: { type: string }
|
||
message: { type: string }
|
||
data:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
firstname: { type: string }
|
||
lastname: { type: string }
|
||
date: { type: string, format: date }
|
||
status: { type: string, enum: [present, absent, late] }
|
||
reason: { type: string, nullable: true }
|
||
|
||
InvoiceList:
|
||
type: object
|
||
properties:
|
||
status: { type: string }
|
||
message: { type: string }
|
||
data:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id: { type: integer }
|
||
invoice_number: { type: string }
|
||
parent_id: { type: integer }
|
||
amount: { type: number }
|
||
status: { type: string }
|
||
created_at: { type: string }
|
||
|
||
EnrollmentResponse:
|
||
type: object
|
||
properties:
|
||
status: { type: string }
|
||
message: { type: string }
|
||
data:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id: { type: integer }
|
||
firstname: { type: string }
|
||
lastname: { type: string }
|
||
enrollment:
|
||
type: object
|
||
properties:
|
||
enrollment_status: { type: string }
|
||
admission_status: { type: string, nullable: true }
|
||
|
||
EventParticipationResponse:
|
||
type: object
|
||
properties:
|
||
status: { type: string }
|
||
message: { type: string }
|
||
data:
|
||
type: object
|
||
properties:
|
||
events:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id: { type: integer }
|
||
name: { type: string }
|
||
amount: { type: number }
|
||
start_date: { type: string }
|
||
end_date: { type: string }
|
||
charges:
|
||
type: object
|
||
additionalProperties:
|
||
type: object
|
||
properties:
|
||
student_id: { type: integer }
|
||
event_id: { type: integer }
|
||
participation: { type: string, enum: [yes, no] }
|
||
charged: { type: number }
|
||
date: { type: string, format: date-time }
|
||
|
||
CreateStudentRequest:
|
||
type: object
|
||
properties:
|
||
firstname: { type: string }
|
||
lastname: { type: string }
|
||
dob: { type: string, format: date }
|
||
age: { type: integer }
|
||
gender: { type: string }
|
||
registration_grade: { type: string }
|
||
photo_consent: { type: integer, enum: [0,1] }
|
||
rfid_tag: { type: string }
|
||
is_new: { type: integer, enum: [0,1], default: 1 }
|
||
|
||
UpdateStudentRequest:
|
||
allOf:
|
||
- $ref: '#/components/schemas/CreateStudentRequest'
|
||
|
||
EmergencyContactsList:
|
||
type: object
|
||
properties:
|
||
status: { type: string }
|
||
message: { type: string }
|
||
data:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id: { type: integer }
|
||
parent_id: { type: integer }
|
||
emergency_contact_name: { type: string }
|
||
cellphone: { type: string }
|
||
email: { type: string }
|
||
relation: { type: string }
|
||
|
||
SaveEmergencyContactRequest:
|
||
type: object
|
||
properties:
|
||
id: { type: integer, nullable: true }
|
||
emergency_contact_name: { type: string }
|
||
cellphone: { type: string }
|
||
email: { type: string, nullable: true }
|
||
relation: { type: string, nullable: true }
|
||
|
||
AuthorizedUsersList:
|
||
type: object
|
||
properties:
|
||
status: { type: string }
|
||
message: { type: string }
|
||
data:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id: { type: integer }
|
||
user_id: { type: integer }
|
||
firstname: { type: string }
|
||
lastname: { type: string }
|
||
email: { type: string }
|
||
phone_number: { type: string }
|
||
relation_to_user: { type: string }
|
||
status: { type: string }
|
||
|
||
AddAuthorizedUserRequest:
|
||
type: object
|
||
required: [firstname, lastname, email, phone_number]
|
||
properties:
|
||
firstname: { type: string }
|
||
lastname: { type: string }
|
||
email: { type: string }
|
||
phone_number: { type: string }
|
||
relation_to_user: { type: string }
|
||
|
||
ParentEnrollClassesData:
|
||
type: object
|
||
properties:
|
||
status: { type: string }
|
||
message: { type: string }
|
||
data:
|
||
type: object
|
||
properties:
|
||
students:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id: { type: integer }
|
||
firstname: { type: string }
|
||
lastname: { type: string }
|
||
class_section: { type: string }
|
||
admission_status: { type: string, nullable: true }
|
||
enrollment_status: { type: string }
|
||
disable_enroll: { type: boolean }
|
||
schoolYears:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
school_year: { type: string }
|
||
selectedYear: { type: string }
|
||
isEditable: { type: boolean }
|
||
withdrawalDeadline: { type: string, format: date }
|
||
lastDayOfRegistration: { type: string, format: date }
|
||
schoolStartDate: { type: string, format: date }
|
||
|
||
UpdateParentEnrollmentsRequest:
|
||
type: object
|
||
properties:
|
||
enroll:
|
||
type: array
|
||
items: { type: integer }
|
||
example: [101, 102]
|
||
withdraw:
|
||
type: array
|
||
items: { type: integer }
|
||
example: [103]
|
||
|
||
UpdateParentEnrollmentsResponse:
|
||
type: object
|
||
properties:
|
||
status: { type: string }
|
||
message: { type: string }
|
||
data:
|
||
type: object
|
||
properties:
|
||
enrolled:
|
||
type: array
|
||
items: { type: integer }
|
||
withdrawn:
|
||
type: array
|
||
items: { type: integer }
|
||
messages:
|
||
type: array
|
||
items: { type: string }
|