chamomind/elearning
7
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages 3 Wiki Activity Actions
elearning/docs/api-docs/api_v3_examples.md

9.8 KiB
Raw Blame History

API Usage Examples for ERD v3

🔐 Authentication

Register with Username

POST /api/auth/register
Content-Type: application/json

{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "SecurePass123!",
  "first_name": "John",
  "last_name": "Doe",
  "prefix": "Mr."
}

Response 201:

{
  "user": {
    "id": 1,
    "username": "john_doe",
    "email": "john@example.com",
    "role": {
      "id": 3,
      "code": "STUDENT",
      "name": {
        "th": "นักเรียน",
        "en": "Student"
      }
    },
    "profile": {
      "prefix": "Mr.",
      "first_name": "John",
      "last_name": "Doe"
    }
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Login with Username

POST /api/auth/login
Content-Type: application/json

{
  "username": "john_doe",
  "password": "SecurePass123!"
}

Response 200:

{
  "user": {
    "id": 1,
    "username": "john_doe",
    "email": "john@example.com",
    "role": {
      "code": "STUDENT",
      "name": {"th": "นักเรียน", "en": "Student"}
    }
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Login with Email

POST /api/auth/login
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "SecurePass123!"
}

Response: Same as username login

👤 User Profile

Get User Info

GET /api/users/me
Authorization: Bearer <token>

Response 200:

{
  "id": 1,
  "username": "john_doe",
  "email": "john@example.com",
  "email_verified_at": "2026-01-01T10:00:00Z",
  "role": {
    "id": 3,
    "code": "STUDENT",
    "name": {"th": "นักเรียน", "en": "Student"}
  },
  "created_at": "2026-01-01T10:00:00Z"
}

Get User Profile Details

GET /api/users/me/profile
Authorization: Bearer <token>

Response 200:

{
  "id": 1,
  "user_id": 1,
  "prefix": "Mr.",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "0812345678",
  "avatar_url": "https://s3.../avatars/john.jpg",
  "created_at": "2026-01-01T10:00:00Z",
  "updated_at": "2026-01-05T15:30:00Z"
}

Update Profile

PUT /api/users/me/profile
Authorization: Bearer <token>
Content-Type: application/json

{
  "prefix": "Dr.",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "0898765432",
  "avatar_url": "https://s3.../avatars/john-new.jpg"
}

Response 200:

{
  "id": 1,
  "prefix": "Dr.",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "0898765432",
  "avatar_url": "https://s3.../avatars/john-new.jpg",
  "updated_at": "2026-01-06T11:00:00Z",
  "updated_by": 1
}

🎓 Multi-Instructor Support

List Course Instructors

GET /api/instructor/courses/1/instructors
Authorization: Bearer <token>

Response 200:

{
  "instructors": [
    {
      "id": 1,
      "user_id": 5,
      "username": "prof_smith",
      "name": "Prof. John Smith",
      "avatar_url": "https://s3.../avatars/smith.jpg",
      "is_primary": true,
      "joined_at": "2026-01-01T10:00:00Z"
    },
    {
      "id": 2,
      "user_id": 10,
      "username": "dr_jane",
      "name": "Dr. Jane Doe",
      "avatar_url": "https://s3.../avatars/jane.jpg",
      "is_primary": false,
      "joined_at": "2026-01-05T14:00:00Z"
    }
  ]
}

Add Instructor to Course

POST /api/instructor/courses/1/instructors
Authorization: Bearer <token>
Content-Type: application/json

{
  "user_id": 15,
  "is_primary": false
}

Response 201:

{
  "id": 3,
  "course_id": 1,
  "user_id": 15,
  "username": "ta_mike",
  "name": "Mike Johnson",
  "is_primary": false,
  "joined_at": "2026-01-06T11:00:00Z"
}

Set Primary Instructor

PUT /api/instructor/courses/1/instructors/10/primary
Authorization: Bearer <token>

Response 200:

{
  "message": "Primary instructor updated",
  "instructors": [
    {
      "user_id": 5,
      "is_primary": false
    },
    {
      "user_id": 10,
      "is_primary": true
    }
  ]
}

Remove Instructor

DELETE /api/instructor/courses/1/instructors/15
Authorization: Bearer <token>

Response 200:

{
  "message": "Instructor removed successfully"
}

Error 400 (Last instructor):

{
  "error": {
    "code": "LAST_INSTRUCTOR",
    "message": "Cannot remove the last instructor from course"
  }
}

🎓 Certificates

Get My Certificates

GET /api/students/certificates
Authorization: Bearer <token>

Response 200:

{
  "certificates": [
    {
      "id": 1,
      "course_id": 1,
      "course_title": "Python for Beginners",
      "completion_date": "2026-01-05",
      "file_path": "https://s3.../certificates/cert-user1-course1.pdf",
      "issued_at": "2026-01-05T16:00:00Z"
    },
    {
      "id": 2,
      "course_id": 3,
      "course_title": "Web Development Bootcamp",
      "completion_date": "2025-12-20",
      "file_path": "https://s3.../certificates/cert-user1-course3.pdf",
      "issued_at": "2025-12-20T10:00:00Z"
    }
  ]
}

Get Course Certificate

GET /api/students/courses/1/certificate
Authorization: Bearer <token>

Response 200:

{
  "id": 1,
  "course_id": 1,
  "course_title": "Python for Beginners",
  "student_name": "John Doe",
  "completion_date": "2026-01-05",
  "file_path": "https://s3.../certificates/cert-user1-course1.pdf",
  "issued_at": "2026-01-05T16:00:00Z"
}

Error 404 (Not completed):

{
  "error": {
    "code": "CERTIFICATE_NOT_FOUND",
    "message": "Certificate not available. Complete the course first."
  }
}

Error 400 (Course doesn't issue certificates):

{
  "error": {
    "code": "NO_CERTIFICATE",
    "message": "This course does not issue certificates"
  }
}

🔒 Role Management (Admin)

List All Roles

GET /api/admin/roles
Authorization: Bearer <admin-token>

Response 200:

{
  "roles": [
    {
      "id": 1,
      "code": "ADMIN",
      "name": {
        "th": "ผู้ดูแลระบบ",
        "en": "Administrator"
      },
      "description": {
        "th": "มีสิทธิ์เต็มในการจัดการระบบ",
        "en": "Full system access"
      }
    },
    {
      "id": 2,
      "code": "INSTRUCTOR",
      "name": {
        "th": "ผู้สอน",
        "en": "Instructor"
      },
      "description": {
        "th": "สามารถสร้างและจัดการคอร์สเรียน",
        "en": "Can create and manage courses"
      }
    },
    {
      "id": 3,
      "code": "STUDENT",
      "name": {
        "th": "นักเรียน",
        "en": "Student"
      },
      "description": {
        "th": "สามารถลงทะเบียนและเรียนคอร์ส",
        "en": "Can enroll and learn courses"
      }
    }
  ]
}

Get Role Details

GET /api/admin/roles/2
Authorization: Bearer <admin-token>

Response 200:

{
  "id": 2,
  "code": "INSTRUCTOR",
  "name": {
    "th": "ผู้สอน",
    "en": "Instructor"
  },
  "description": {
    "th": "สามารถสร้างและจัดการคอร์สเรียน",
    "en": "Can create and manage courses"
  },
  "user_count": 45,
  "created_at": "2026-01-01T00:00:00Z"
}

📚 Course with Certificate

Get Course Details (with have_certificate)

GET /api/courses/1

Response 200:

{
  "id": 1,
  "title": {
    "th": "Python สำหรับผู้เริ่มต้น",
    "en": "Python for Beginners"
  },
  "description": {...},
  "price": 990,
  "is_free": false,
  "have_certificate": true,
  "instructors": [
    {
      "user_id": 5,
      "name": "Prof. John Smith",
      "is_primary": true
    },
    {
      "user_id": 10,
      "name": "Dr. Jane Doe",
      "is_primary": false
    }
  ],
  "total_lessons": 50,
  "total_duration": 1200,
  "status": "APPROVED"
}

🎯 Quiz with show_answers_after_completion

Get Quiz

GET /api/students/quizzes/1
Authorization: Bearer <token>

Response 200:

{
  "id": 1,
  "title": {"th": "แบบทดสอบท้ายบท", "en": "Chapter Quiz"},
  "description": {...},
  "passing_score": 60,
  "time_limit": 30,
  "shuffle_questions": true,
  "shuffle_choices": true,
  "show_answers_after_completion": true,
  "questions": [...]
}

Submit Quiz (with answers shown)

POST /api/students/quizzes/1/submit
Authorization: Bearer <token>
Content-Type: application/json

{
  "answers": [
    {"question_id": 1, "choice_id": 3},
    {"question_id": 2, "choice_id": 7}
  ]
}

Response 200 (show_answers_after_completion = true):

{
  "attempt_id": 1,
  "score": 75,
  "total_questions": 10,
  "correct_answers": 8,
  "is_passed": true,
  "answers": [
    {
      "question_id": 1,
      "question": {"th": "Python คืออะไร?"},
      "your_answer": 3,
      "correct_answer": 3,
      "is_correct": true,
      "explanation": {"th": "Python เป็นภาษาโปรแกรมมิ่ง..."}
    },
    {
      "question_id": 2,
      "question": {"th": "ตัวแปรใน Python..."},
      "your_answer": 7,
      "correct_answer": 8,
      "is_correct": false,
      "explanation": {"th": "ตัวแปรใน Python ไม่ต้องประกาศชนิดข้อมูล"}
    }
  ]
}

Response 200 (show_answers_after_completion = false):

{
  "attempt_id": 1,
  "score": 75,
  "total_questions": 10,
  "correct_answers": 8,
  "is_passed": true
}

🔗 Related Documentation