Skip to main content

​
1. API Purpose

The Student Management API is the central registry of the Skole platform. It powers all other modules by establishing student identities and linking them to parents, staff, and school-specific data.

​
2. Endpoint Definition

MethodRouteAuthDescription
GET/parent-app/student-detail🔐 JWTView child’s full profile
GET/teachers-app/students🔐 JWTList assigned students (Teacher)
GET/web-app/students🔐 JWTFull student registry (Admin)
PUT/web-app/students/:id🔐 JWTUpdate student record
POST/web-app/students/:id/archive🔐 JWTArchive student record
POST/web-app/students/:id/reset-password🔐 JWTReset parent PIN

​
3. Authentication Flow

  • Guardians: Access is restricted to children linked to the parent’s phone_no in the database.
  • Teachers: Access is restricted to students assigned to them via the staff_student junction table.
  • Admins: Full access scoped by skole_id.

​
4. Request Structure

​
GET /teachers-app/students

Query Parameters:
FieldTypeRequiredDescription
skole_idstringYesSchool identifier.
gradestringNoFilter by grade/class.

​
GET /web-app/students

Query Parameters:
FieldTypeRequiredDescription
skole_idstringYesSchool identifier.
searchstringNoSearch by name or roll number.
gradestringNoFilter by grade/class.
statusstringNoEnum: active, archived, all.
pagenumberNoDefault: 1.
limitnumberNoDefault: 10.

​
PUT /web-app/students/:id

Request Body: 
{
  "student_full_name": "Aarav Sharma",
  "gender": "Male",
  "grade": "Grade 5-A",
  "date_of_birth": "2013-05-15",
  "blood_group": "B+",
  "phone_no": "9876543210"
}

​
POST /web-app/students/:id/archive

URL Parameters:
FieldTypeDescription
idnumberStudent ID to archive.

​
POST /web-app/students/:id/reset-password

Request Body: 
{
  "password": "NewSecurePassword123"
}

​
5. Response Structure

​
Success: Child Profile Detail (200 OK)

Route: GET /parent-app/student-detail 
{
  "success": true,
  "data": {
    "student": {
      "id": 45,
      "student_full_name": "Aarav Sharma",
      "roll_no": "20240045",
      "grade": "Grade 5-A"
    },
    "guardian": { "father_name": "Rajesh Kumar" }
  }
}

​
Success: Teacher Student List (200 OK)

Route: GET /teachers-app/students 
{
  "success": true,
  "data": [
    {
      "id": 45,
      "student_full_name": "Aarav Sharma",
      "roll_no": "20240045"
    }
  ]
}

​
Success: Admin Student Registry (200 OK)

Route: GET /web-app/students 
{
  "success": true,
  "data": {
    "students": [...],
    "pagination": { "total": 1200, "page": 1 }
  }
}

​
Success: Student Updated (200 OK)

Route: PUT /web-app/students/:id 
{
  "success": true,
  "message": "Student record updated successfully"
}

​
Success: Record Archived (200 OK)

Route: POST /web-app/students/:id/archive 
{
  "success": true,
  "message": "Student moved to archives"
}

​
Success: PIN Reset (200 OK)

Route: POST /web-app/students/:id/reset-password 
{
  "success": true,
  "message": "Parent PIN has been reset"
}

​
6. Error Responses

HTTP CodeDescription
404Student not found
403Attempting to access a student not assigned to the user

​
7. Security Considerations

  • PIN Security: Resetting a PIN requires Admin-level JWT.
  • Isolation: Cross-tenant access is blocked via the global SkoleGuard.

​
8. Token Usage

GET /parent-app/student-detail?roll_no=A001
Authorization: Bearer <TOKEN>

​
9. Token Refresh

N/A.

​
10. Logout / Session Invalidation

N/A.

​
11. Usage Example (cURL)

curl -H "Authorization: Bearer <TOKEN>" \
"http://localhost:3000/web-app/students?grade=Grade%205"

​
12. Notes / Special Behaviors

  • Lifecycle: Students can move from registered to active, inactive, and eventually archived.
  • Roll Numbers: Roll numbers must be unique within a school (skole_id).