Skip to content

API Endpoints

Jump to bottom
Justin edited this page Jun 2, 2024 · 7 revisions

Create User

Attempt to create an account, if successful send email confirmation. Will check if email is in use, will not validate for matching passwords or email formatting.

Authentication

Requires session cookie.

URL

POST /users

Request Form Data

Parameter Type Description Requirement Type
email string Email address of the user. Required
password string Password of the user. Required
confirmedPassword string Password of the user for validation. Required
firstName string User's first name. Required
lastName string User's last name. Required

Example Request

fetch(`http://localhost:3001/users`, {
  method: 'POST',
  body: new URLSearchParams({
    'email': '[email protected]',
    'password': 'YourSecurePassword',
    'confirmedPassword': 'YourSecurePassword',
    'firstName': 'John',
    'lastName': 'Doe'
  })
}).then(response => response.json())
  .then(data => ...);

Response Parameters

Parameter Type Description
token string The user token generated upon successful account creation. (Only for successful requests)
error string Error message detailing why the request failed. (Only for failed requests)

Status Codes

Status Code Description
201 Account created successfully.
400 Bad request, required information missing or invalid.
500 Internal server error.

Example Response

{
  'token': '6d167d57abd239ff77f67fd402d510b1f3b1286b10d03e7c48b30e200f529a8e'
}

Update Password

Request password reset by sending an OTP reset code to the user's email if the email is attached to an account.

Authentication

None required, but utilizes user's email for identification.

URL

PUT /users/password?email={email}

Request Form Data

N/A - URL Query Parameters used.

Example Request

fetch(`http://localhost:3001/users/[email protected]`, {
  method: 'PUT'
}).then(response => response.json())
  .then(data => ...);

Response Parameters

N/A

Status Codes

Status Code Description
200 Email sent or account not found (for privacy).
500 Server error.

Example Response

{
  // Response is indicated through HTTP status code
}

Authenticate

Authenticate the user with credentials provided or use the token to authenticate.

Authentication

Optional initial authentication via email and password, or via session token.

URL

POST /users/authenticate

Request Form Data

Parameter Type Description Requirement Type
email string Email address of the user Optional
password string Password of the user Optional

Example Request

fetch(`http://localhost:3001/users/authenticate`, {
  method: 'POST',
  body: JSON.stringify({
    'email': '[email protected]',
    'password': 'YourSecurePassword'
  }),
  headers: {
    'Content-Type': 'application/json'
  }
}).then(response => response.json())
  .then(data => ...);

Response Parameters

Parameter Type Description
token string The user token generated upon successful authentication.

Status Codes

Status Code Description
200 Authentication successful.
401 Unauthenticated, wrong credentials provided.
500 Internal server error.

Example Response

{
  'token': '6d167d57abd239ff77f67fd402d510b1f3b1286b10d03e7c48b30e200f529a8e'
}

Get User Information

Retrieve user information by user ID after authenticating token.

Authentication

Requires valid user token.

URL

GET /users/:user_id

Request Form Data

N/A - URL Parameters used.

Example Request

fetch(`http://localhost:3001/users/12345`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer 6d167d57abd239ff77f67fd402d510b1f3b1286b10d03e7c48b30e200f529a8e'
  }
}).then(response => response.json())
  .then(data => ...);

Response Parameters

Parameter Type Description
email string Email address of the user.
firstName string First name of the user.
lastName string Last name of the user.

Status Codes

Status Code Description
200 User information successfully retrieved.
404 User not found.
401 Unauthorized access attempt.

Example Response

{
  'email': '[email protected]',
  'firstName': 'John',
  'lastName': 'Doe'
}

Edit User Information

Edit account information after authenticating with the old password or password reset token.

Authentication

Requires valid user token and either old password validation or password reset token.

URL

PUT /users/:user_id

Request Form Data

Parameter Type Description Requirement Type
email string New email address of the user. Optional
oldPassword string Old password of the user. Optional
newPassword string New password of the user. Optional
confirmedPassword string New password of the user for validation. Optional
firstName string New first name of the user. Optional
lastName string New last name of the user. Optional
emailConfirmation string Confirmation code sent to the new email. Optional

Example Request

fetch(`http://localhost:3001/users/12345`, {
  method: 'PUT',
  body: JSON.stringify({
    'email': '[email protected]',
    'oldPassword': 'YourSecurePassword',
    'newPassword': 'YourNewSecurePassword',
    'confirmedPassword': 'YourNewSecurePassword',
    'firstName': 'Johnathan',
    'lastName': 'Doe'
  }),
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer 6d167d57abd239ff77f67fd402d510b1f3b1286b10d03e7c48b30e200f529a8e'
  }
}).then(response => response.json())
  .then(data => ...);

Response Parameters

Parameter Type Description
email string Updated email address of the user.
firstName string Updated first name of the user.
lastName string Updated last name of the user.

Status Codes

Status Code Description
200 User information updated successfully.
400 Bad request, validation errors.
401 Unauthorized, wrong old password or token.
500 Internal server error.

Example Response

{
  'email': '[email protected]',
  'firstName': 'Johnathan',
  'lastName': 'Doe'
}

Delete User

Delete a user account and associated data after authenticating token.

Authentication

Requires valid user token.

URL

DELETE /users/:user_id

Request Form Data

N/A - URL Parameters used.

Example Request

fetch(`http://localhost:3001/users/12345`, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer 6d167d57abd239ff77f67fd402d510b1f3b1286b10d03e7c48b30e200f529a8e'
  }
}).then(response => response.json())
  .then(data => ...);

Response Parameters

N/A

Status Codes

Status Code Description
200 Account successfully deleted.
404 Account not found or not authorized to delete.
500 Server error.

Example Response

{
  // Response is indicated through HTTP status code
}

List Courses

List all courses a user is enrolled in, with differences between teacher and student roles.

Authentication

Requires valid user token.

PUT /users/:userId/confirm

  • Description: Confirm the user's email address
  • Request:
    • Params: userId: "string"
    • Body: 
      {
	"emailConfirmationCode": "string"
}
  • Response:
    • Success: 200 OK
    • Error: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 498 Invalid Token

GET /users/:userId/confirm

  • Description: Request a new email confirmation code
  • Request:
    • Params: userId: "string"
  • Response:
    • Success: 200 OK
    • Error: 400 Bad Request, 403 Forbidden, 404 Not Found

URL

GET /courses

Request Form Data

N/A

Example Request

fetch(`http://localhost:3001/courses`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer 6d167d57abd239ff77f67fd402d510b1f3b1286b10d03e7c48b30e200f529a8e'
  }
}).then(response => response.json())
  .then(data => ...);

Response Parameters

Parameter Type Description
courses Array List of courses the user is enrolled in, with role-specific data.

Status Codes

Status Code Description
200 Successfully retrieved list of courses.
401 Unauthorized, token invalid.
500 Internal server error.

Example Response

{
  'courses': [...]
}

Create Course

Create a course and enroll the creator as a teacher.

Authentication

Requires valid user token.

URL

POST /courses

Request Form Data

Parameter Type Description Requirement Type
name string Name of the course. Required
description string Description of the course. Required

Example Request

fetch(`http://localhost:3001/courses`, {
  method: 'POST',
  body: JSON.stringify({
    'name': 'Advanced Mathematics',
    'description': 'A course on advanced mathematics topics.'
  }),
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer 6d167d57abd239ff77f67fd402d510b1f3b1286b10d03e7c48b30e200f529a8e'
  }
}).then(response => response.json())
  .then(data => ...);

Response Parameters

Parameter Type Description
id string ID of the newly created course.
name string Name of the newly created course.
description string Description of the newly created course.

Status Codes

Status Code Description
201 Course created successfully.
400 Bad request, required information missing or invalid.
401 Unauthorized, token invalid.
500 Internal server error.

Example Response

{
  'id': 'course123',
  'name': 'Advanced Mathematics',
  'description': 'A course on advanced mathematics topics.'
}

Join Course

Enroll a user in a course section using a join code.

Authentication

Requires valid user token.

URL

POST /courses/join

Request Form Data

Parameter Type Description Requirement Type
joinCode string Join code for the course section. Required

Example Request

fetch(`http://localhost:3001/courses/join`, {
  method: 'POST',
  body: JSON.stringify({
    'joinCode': 'ABC123'
  }),
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer 6d167d57abd239ff77f67fd402d510b1f3b1286b10d03e7c48b30e200f529a8e'
  }
}).then(response => response.json())
  .then(data => ...);

Response Parameters

Parameter Type Description
section string The section the user was enrolled

Status Codes

Status Code Description
200 Successfully joined the course.
400 Bad request, join code invalid.
401 Unauthorized, token invalid.
404 Course or section not found.
500 Internal server error.

Example Response

PUT /courses/:course_id

  • Description: Update a course's information
  • Request:
    • Params: course_id: "string"
    • Body: 
      {
  "name": "string",
  "description": "string",
  "published": "boolean",
  ...
}
  • Response:
    • Success: 200 OK, { course: { ... } }
    • Error: 400 Bad Request, 403 Forbidden, { error: "message" }

DELETE /courses/:course_id

  • Description: Delete a course
  • Request:
    • Params: course_id: "string"
  • Response:
    • Success: 204 No Content
    • Error: 403 Forbidden, { error: "message" }

Nested Routes

  • Description: Additional endpoints related to courses
    • /courses/:course_id/lectures
    • /courses/:course_id/enrollments
    • /courses/:course_id/questions
    • /courses/:course_id/sections
    • /courses/:course_id/sections/:section_id/lectures/:lecture_id/responses
    • /courses/:course_id/sections/:section_id/grades

Enrollments

GET /courses/:course_id/enrollments

  • Description: Get the roster for a course
  • Request: None
  • Response:
    • Success: 200 OK, { enrollments: [...] }
    • Error: 403 Forbidden, { error: "Only the teacher for a course can view the roster" }

DELETE /courses/:course_id/enrollments/:enrollment_id

  • Description: Delete a student from a course roster
  • Request:
    • Params: course_id: "string", enrollment_id: "string"
  • Response:
    • Success: 204 No Content
    • Error: 403 Forbidden, 400 Bad Request, { error: "message" }

PUT /courses/:course_id/enrollments/:enrollment_id

  • Description: Change a student's section
  • Request:
    • Params: course_id: "string", enrollment_id: "string"
    • Body: 
      {
	"sectionId": "string"
}
  • Response:
    • Success: 200 OK, { enrollment: { ... } }
    • Error: 403 Forbidden, 400 Bad Request, { error: "message" }

Courses

GET /courses

  • Description: Get the list of courses for the authenticated user
  • Request: None
  • Response:
    • Success: 200 OK, { studentCourses: [...], teacherCourses: [...] }

POST /courses

  • Description: Create a new course
  • Request:
    • Body: 
      {
  "name": "string",
  ...
}
  • Response:
    • Success: 201 Created, { course: { ... }, enrollment: { ... } }
    • Error: 400 Bad Request, { error: "message" }

POST /courses/join

  • Description: Join a course using a join code
  • Request:
    • Body: 
      {
	"joinCode": "string"
}
  • Response:
    • Success: 201 Created, { section: { ... }, course: { ... }, enrollment: { ... } }
    • Error: 400 Bad Request, 404 Not Found, { error: "message" }

PUT /courses/:course_id

  • Description: Update a course's information
  • Request:
    • Params: course_id: "string"
    • Body: 
      {
  "name": "string",
  "description": "string",
  "published": "boolean",
  ...
}
  • Response:
    • Success: 200 OK, { course: { ... } }
    • Error: 400 Bad Request, 403 Forbidden, { error: "message" }

DELETE /courses/:course_id

  • Description: Delete a course
  • Request:
    • Params: course_id: "string"
  • Response:
    • Success: 204 No Content
    • Error: 403 Forbidden, { error: "message" }

Nested Routes

  • Description: Additional endpoints related to courses
    • /courses/:course_id/lectures
    • /courses/:course_id/enrollments
    • /courses/:course_id/questions
    • /courses/:course_id/sections
    • /courses/:course_id/sections/:section_id/lectures/:lecture_id/responses
    • /courses/:course_id/sections/:section_id/grades

Enrollments

GET /courses/:course_id/enrollments

  • Description: Get the roster for a course
  • Request: None
  • Response:
    • Success: 200 OK, { enrollments: [...] }
    • Error: 403 Forbidden, { error: "Only the teacher for a course can view the roster" }

DELETE /courses/:course_id/enrollments/:enrollment_id

  • Description: Delete a student from a course roster
  • Request:
    • Params: course_id: "string", enrollment_id: "string"
  • Response:
    • Success: 204 No Content
    • Error: 403 Forbidden, 400 Bad Request, { error: "message" }

PUT /courses/:course_id/enrollments/:enrollment_id

  • Description: Change a student's section
  • Request:
    • Params: course_id: "string", enrollment_id: "string"
    • Body: 
      {
	"sectionId": "string"
}
  • Response:
    • Success: 200 OK, { enrollment: { ... } }
    • Error: 403 Forbidden, 400 Bad Request, { error: "message" }

Sections

POST /courses/:course_id/sections

  • Description: Add a new section to a course
  • Request:
    • Params: course_id: "string"
    • Body: 
      {
	"number": "string"
}
  • Response:
    • Success: 201 Created, { section: { ... } }
    • Error: 400 Bad Request, { error: "message" }

GET /courses/:course_id/sections

  • Description: Get all sections within a course
  • Request: None
  • Response:
    • Success: 200 OK, [ { ... } ]
    • Error: 403 Forbidden, { error: "message" }

GET /courses/:course_id/sections/:section_id

  • Description: Get a specific section and lectures for that section
  • Request:
    • Params: course_id: "string", section_id: "string"
  • Response:
    • Success: 200 OK, { section: { ... }, lectures: [...] }
    • Error: 403 Forbidden, 404 Not Found, { error: "message" }

PUT /courses/:course_id/sections/:section_id

  • Description: Update a specific section
  • Request:
    • Params: course_id: "string", section_id: "string"
    • Body: 
      {
	"number": "string"
}
  • Response:
    • Success: 200 OK
    • Error: 400 Bad Request, 403 Forbidden, { error: "message" }

Nested Routes

  • Description: Additional endpoints related to sections
    • /courses/:course_id/sections/:section_id/lectures

Responses

POST /courses/:course_id/lectures/:lecture_id/questions/:question_id/responses

  • Description: Submit a response to a question in a lecture
  • Request:
    • Params: course_id: "string", lecture_id: "string", question_id: "string"
    • Body: 
      {
  "answers": { ... }
}
  • Response:
    • Success: 201 Created, { response: { ... } }
    • Error: 400 Bad Request, 403 Forbidden, { error: "message" }

PUT /courses/:course_id/lectures/:lecture_id/questions/:question_id/responses/:response_id

  • Description: Resubmit a response to a question in a lecture
  • Request:
    • Params: course_id: "string", lecture_id: "string", question_id: "string", response_id: "string"
    • Body: 
      {
  "answers": { ... }
}
  • Response:
    • Success: 200 OK, { response: { ... } }
    • Error: 400 Bad Request, 403 Forbidden, { error: "message" }

Questions

GET /courses/:course_id/questions

  • Description: Get all questions for a given course
  • Request:
    • Params: course_id: "string"
    • Query: search="string"&page="number"&perPage="number"
  • Response:
    • Success: 200 OK, { questions: [...], links: { nextPage: "url", prevPage: "url" } }
    • Error: 403 Forbidden, { error: "message" }

POST /courses/:course_id/questions

  • Description: Create a new question for a given course
  • Request:
    • Params: course_id: "string"
    • Body: 
      {
  ...
}
  • Response:
    • Success: 201 Created, { question: { ... } }
    • Error: 400 Bad Request, { error: "message" }

Lecture Summaries

GET /courses/:course_id/sections/:section_id/lectures/:lecture_id/responses

  • Description: Get the responses to questions given in a lecture
  • Request:
    • Params: course_id: "string", section_id: "string", lecture_id: "string"
  • Response:
    • Success: 200 OK, [ { ... } ]
    • Error: 403 Forbidden, { error: "message" }

Lectures for Section

PUT /courses/:course_id/sections/:section_id/lectures/:lecture_id

  • Description: (Un)publish a lecture in a section
  • Request:
    • Params: course_id: "string", section_id: "string", lecture_id: "string"
  • Response:
    • Success: 200 OK
    • Error: 403 Forbidden, { error: "message" }, 404 Not Found

Questions in Lecture

GET /courses/:course_id/lectures/:lecture_id/questions/:question_id

  • Description: Get a question inside a lecture
  • Request:
    • Params: course_id: "string", lecture_id: "string", question_id: "string"
  • Response:
    • Success: 200 OK, { ...questionFields, ...questionInLectureFields }
    • Error: 400 Bad Request, 403 Forbidden, 404 Not Found, { error: "message" }

PUT /courses/:course_id/lectures/:lecture_id/questions/:question_id

  • Description: (Un)publish a question inside a lecture
  • Request:
    • Params: course_id: "string", lecture_id: "string", question_id: "string"
  • Response:
    • Success: 200 OK
    • Error: 400 Bad Request, 403 Forbidden, 404 Not Found, { error: "message" }

POST /courses/:course_id/lectures/:lecture_id/questions/:question_id

  • Description: Connect a question to a lecture
  • Request:
    • Params: course_id: "string", lecture_id: "string", question_id: "string"
    • Body: 
      {
	"order": "number",
	"published": "boolean"
}
  • Response:
    • Success: 201 Created, { ...newQuestionInLectureFields }
    • Error: 400 Bad Request, 403 Forbidden, { error: "message" }

PUT /courses/:course_id/lectures/:lecture_id/questions

  • Description: Swap the order of two questions in a lecture
  • Request:
    • Params: course_id: "string", lecture_id: "string"
    • Body: 
      {
	"questionIdOne": "string",
	"questionIdTwo": "string"
}
  • Response:
    • Success: 200 OK
    • Error: 400 Bad Request, 403 Forbidden, { error: "message" }

DELETE /courses/:course_id/lectures/:lecture_id/questions/:question_id

  • Description: Remove a question from a lecture
  • Request:
    • Params: course_id: "string", lecture_id: "string", question_id: "string"
  • Response:
    • Success: 204 No Content
    • Error: 400 Bad Request, 403 Forbidden, 404 Not Found, { error: "message" }

Nested Routes

  • Description: Additional endpoints related to questions in lecture
    • /courses/:course_id/lectures/:lecture_id/questions/:question_id/responses

Grades

GET /courses/:course_id/grades

  • Description: Get grades for each student in the course (teacher) or get their own grade for the course (student)
  • Request:
    • Params: course_id: "string"
  • Response:
    • Success: 200 OK, [...]
    • Error: 403 Forbidden, { error: "message" }

GET /courses/:course_id/sections/:section_id/grades/all

  • Description: Get all grades for a section
  • Request:
    • Params: course_id: "string", section_id: "string"
  • Response:
    • Success: 200 OK, [{ studentId, studentName, grade }]
    • Error: 403 Forbidden, { error: "message" }

GET /courses/:course_id/sections/:section_id/grades/:student_id

  • Description: Get grades for a specific student in a section
  • Request:
    • Params: course_id: "string", section_id: "string", student_id: "string"
  • Response:
    • Success: 200 OK, { studentId, studentName, grade }
    • Error: 403 Forbidden, 404 Not Found, { error: "message" }

User Guides

Admin User Guide

Teacher User Guide

Student User Guide

Developer Documentation

API Endpoints

Contributing Guidelines

Frontend Client Documentation

Backend Server Documentation

Security Information

Project Planning Documents

Product Requirements Document

Software Design and Architecture

Software Development Process

Clone this wiki locally