Skip to content

API_SPECIFICATION.md

Latest commit

 

History

History
293 lines (227 loc) · 10.2 KB

API_SPECIFICATION.md

File metadata and controls

293 lines (227 loc) · 10.2 KB
Raw

REST API Specification

Sentra Tutoring Management Smartboard

Branding: Architected & built by dr Ferdi Iskandar
Brand Entity: Sentra Academic Solutions
Client Tenant Mark: el-kayyisa
Assistant Entity: Kak Kayyisa
Protocol: HTTP/1.1 RESTful JSON
Base URL: http://127.0.0.1:8001/api
Last Updated: 2026-07-28

1. Overview & Authentication Standards

The Sentra Tutoring Management Smartboard API provides full programmatic access to academic operations, master data, session execution, student progression metrics, honor calculations, and payroll workflows.

1.1 Content Negotiation & Encoding

  • All request and response bodies MUST be formatted as UTF-8 encoded JSON (Content-Type: application/json).
  • Timestamp formats follow ISO 8601 extended format (YYYY-MM-DDTHH:MM:SSZ).
  • Currency values are expressed as integer numbers in Indonesian Rupiah (IDR).

1.2 Authentication Schemes

The API supports dual authentication mechanisms:

  1. HTTP-Only Session Cookie: Cookie key bimbel_session automatically sent by client web applications.
  2. HTTP Bearer Token: Header Authorization: Bearer <session_token> for headless integrations and testing.
Client Request ──► [ Auth Interceptor / auth.py ] ──► [ Role Check: require_roles() ] ──► Route Handler

1.3 Standard HTTP Status & Error Response Schema

All error responses return standard HTTP status codes along with a structured JSON error payload:

{
  "detail": "Error description message",
  "error_code": "ERR_UNAUTHORIZED",
  "timestamp": "2026-07-28T08:46:00Z"
}
HTTP Code Description Trigger Condition
200 OK Success Request completed successfully.
201 Created Created Resource successfully created.
400 Bad Request Validation Failure Invalid request payload or illegal query parameter.
401 Unauthorized Unauthenticated Missing or expired session cookie / Bearer token.
403 Forbidden Access Denied Insufficient role permissions under RBAC policy.
404 Not Found Resource Missing Specified ID or collection entity does not exist.
422 Unprocessable Schema Error Pydantic model validation failure.
500 Server Error System Failure Internal server exception.

2. Role-Based Access Control (RBAC) Scoping Matrix

API endpoints are protected by auth.require_roles(). Permitted roles are mapped across the 6 standard system roles:

  • owner (Owner / Leadership)
  • admin_akademik (Academic Administrator)
  • tentor (Tutor / Mentor)
  • finance (Finance Staff)
  • murid_ortu (Student / Parent)
  • content_manager (Content Manager)
Module Router Path Prefix Allowed Roles Special Data Isolation Rules
Auth Router /api/auth All Authenticated / Public Login Login endpoint open; /me requires token.
Master Data Router /api/master owner, admin_akademik Admin writes queued for Owner approval.
Approvals Router /api/approvals owner Admin write approval queue.
Operations Router /api/sessions owner, admin_akademik, tentor Tutors restricted to assigned sessions.
Progression Router /api/students/{id}/progression owner, admin_akademik, tentor, murid_ortu internal_note automatically stripped for murid_ortu.
AI Generation Router /api/ai owner, admin_akademik, tentor Draft generation only; no direct database write.
Overtime Router /api/overtime tentor, admin_akademik, owner Tutors submit; Admin/Owner approve.
Finance Router /api/finance owner, finance Restricted to financial staff.
Payroll Router /api/payroll owner, finance Period lock enforcement.
Reports Router /api/reports owner, admin_akademik, finance CSV/PDF/XLSX export endpoints.

3. Endpoint Catalog

3.1 Authentication Endpoint (/api/auth)

POST /api/auth/login

Authenticates a user and establishes a session.

  • Request Body: 
    {
  "email": "owner.test@bimbel.id",
  "password": "bimbel123"
}
  • Response 200 OK: Sets bimbel_session cookie and returns user profile: 
    {
  "token": "sess_abc123xyz...",
  "user": {
    "id": "usr_001",
    "email": "owner.test@bimbel.id",
    "name": "Dr. Ferdi Iskandar",
    "role": "owner"
  }
}

GET /api/auth/me

Retrieves current authenticated session details.

  • Response 200 OK: User object with active role permissions.

POST /api/auth/logout

Terminates active session and clears authentication cookies.

3.2 Master Data Endpoints (/api/master)

Manage foundational reference tables (Schools, Subjects, Grade Levels, People, Rates, Academic Years).

  • GET /api/master/schools — List registered schools.
  • GET /api/master/subjects — List academic subjects.
  • GET /api/master/grades — List grade levels (SD 1-6, SMP 7-9, SMA 10-12).
  • GET /api/master/people — List tutors, students, parents, and administrative staff.
  • GET /api/master/rates — List tutor hourly rate cards per subject and grade level.
  • GET /api/master/years — List active academic years.
  • POST /api/master/{entity} — Create master data item (Requires owner or queues for approval if created by admin_akademik).

3.3 Learning Session & Operations Endpoints (/api/sessions, /api/schedules)

Manage operational learning sessions, attendance check-ins, evaluation notes, and session verification.

GET /api/sessions

Query operational learning sessions with filters (date, tutor_id, status).

POST /api/sessions/{id}/attendance

Log tutor check-in and student attendance status.

  • Request Body: 
    {
  "tutor_id": "tut_101",
  "attendances": [
    {
      "student_id": "std_501",
      "status": "HADIR",
      "notes": "Hadir tepat waktu"
    },
    {
      "student_id": "std_502",
      "status": "IZIN",
      "notes": "Sakit dengan surat"
    }
  ]
}

POST /api/sessions/{id}/evaluation

Submit session learning score, homework assignment, and tutor notes.

  • Request Body: 
    {
  "topic": "Persamaan Kuadrat & Fungsi Kuadrat",
  "mastery_score": 85,
  "homework": "Latihan 4.2 halaman 78 nomor 1-5",
  "tutor_note": "Siswa memahami konsep dasar dengan baik.",
  "internal_note": "Perlu perhatian ekstra pada pemfaktoran negatif.",
  "ai_assisted": true,
  "ai_fields": ["tutor_note"],
  "ai_model": "nvidia/nemotron-4-340b"
}

POST /api/sessions/{id}/verify

Admin verifies session completion, locking the session and computing tutor honor.

  • Allowed Roles: owner, admin_akademik

3.4 Student Progression & 360 Endpoint (/api/students/{id}/progression)

GET /api/students/{id}/progression

Retrieves longitudinal student progression history, score trends, and subject averages.

  • Response 200 OK (Served to owner, admin_akademik, tentor):

    {
  "student_id": "std_501",
  "student_name": "Ananda Putra",
  "overall_average": 84.5,
  "subject_averages": [
    { "subject": "Matematika", "average": 82.0 },
    { "subject": "Fisika", "average": 87.0 }
  ],
  "evaluations": [
    {
      "date": "2026-07-25",
      "subject": "Matematika",
      "score": 85,
      "topic": "Fungsi Kuadrat",
      "tutor_note": "Sangat kooperatif",
      "internal_note": "Perlu penguatan rumus ABC"
    }
  ]
}

  • Data Privacy Isolation Rule:
    When queried by a user with role murid_ortu, the backend automatically strips internal_note from every item in the evaluations array prior to JSON serialization.

3.5 AI Evaluation Draft Endpoint (/api/ai)

POST /api/ai/draft-evaluation

Generates an AI draft evaluation note based on brief tutor keywords using an OpenAI-compatible endpoint.

  • Request Body: 
    {
  "subject": "Fisika",
  "topic": "Hukum Newton II",
  "raw_notes": "Siswa paham rumus F=ma tapi bingung konversi unit kg ke gram"
}
  • Response 200 OK: 
    {
  "draft_tutor_note": "Siswa telah memahami konsep dasar Hukum Newton II (F=ma). Namun, diperlukan latihan tambahan dalam konversi satuan massa.",
  "suggested_score": 80,
  "provenance": {
    "ai_assisted": true,
    "ai_fields": ["draft_tutor_note", "suggested_score"],
    "ai_model": "nvidia/nemotron-4-340b"
  }
}

3.6 Financial & Payroll Endpoints (/api/finance, /api/payroll)

  • GET /api/finance/rekap-honor — Calculate verified session tutor earnings for a date range.
  • GET /api/payroll/periods — List payroll processing periods.
  • POST /api/payroll/periods — Create or lock a payroll period (owner, finance).
  • POST /api/payroll/payments — Record tutor payout bank transfer details.
  • GET /api/payroll/slips/{tutor_id} — Generate and download official tutor pay slip PDF.

Architected & built by dr Ferdi Iskandar
Sentra Academic Solutions — Sentra Tutoring Management Smartboard