Backend API Design

Author: Zhenyu Yang yangzhenyu@sust.edu.cn, Sixu Wei reisa@sust.edu.cn

Last updated: Apr 05, 2026

The API documentation is written for developers and does not include a machine-readable OpenAPI specification.

API Documentation Index

Module

Description

Authentication and User Accounts

Login, TOTP/WebAuthn two-factor authentication, user management, user import

Classroom Management

Classroom list, details, schedules, available-classroom lookup

Signage Devices

Device activation, signage configuration, schedule retrieval, activation-code management

Courses

Course list and timetable import

Classroom Borrowing

Borrowing requests, review, cancellation, rescheduling

Repair Workflow

Standard repairs, emergency repairs, work-order management

Abuse Reports

Report submission and report handling

Class Check-ins

Check-in session creation and check-in record management

Audit Logs

Log queries and CSV export

Common Utilities

Attachment upload and system configuration

0. Unified Response Format

Except for a small number of file-upload APIs, all APIs return the following structure.

Success:

{
  "code": 0,
  "message": "success",
  "data": { ... }
}

Failure:

{
  "code": 40001,
  "message": "User not found"
}

Common Data Structures

User

Directly mapped from the original requirements document:

{
  "id": 1,
  "user_code": "2024123456",
  "username": "2024123456",
  "full_name": "John Smith",
  "email": "123@school.edu",
  "wxid": "wx_xxxxx",
  "role": "student",
  "roles": ["student"],
  "current_role": "student",
  "status": "active",
  "student_class": "CS UC 2024",
  "date_joined": "2025-01-01T10:00:00",
  "last_login": "2025-03-10T09:00:00",
  "is_totp_enabled": false
}

Classroom

From the database template:

{
  "id": 88,
  "building": "Building A",
  "room_number": "A101",
  "capacity": 60,
  "equipment": {
    "air_conditioner": true,
    "projector": true
  },
  "status": "available"
}

Borrow Application

{
  "id": 103,
  "applicant_id": 12,
  "reviewer_role": "assistant",
  "classroom_id": 88,
  "start_time": "...",
  "end_time": "...",
  "reason": "lecture",
  "status": "pending"
}

Constraints:

  • start_time must be at least 6 hours later than the current time, and end_time must be later than start_time.

  • For the same classroom, only one pending or approved application may exist in an overlapping time range. Time conflicts are checked on submission.

  • Application time limits depend on the applicant role and is_urgent. See Classroom Borrowing.

Conflict checks include:

  • Existing manual borrowings with pending/approved status and source_type=manual.

  • Actual course occurrences from CourseOccurrence.