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

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.