CSC/ECE 517 Spring 2023 E2318: Reimplement Participants Controller

Introduction

Expertiza is an Open Source Rails application which is used by instructors and students for creating assignments and submitting peer reviews. Expertiza allows the instructor to create and customize assignments, create a list of topics the students can sign up for, have students work on teams and also review each other's assignments. Expertiza supports submissions across various document types, including URLs and wiki pages. The Source code of the application can be cloned from Github.

Background

In expertiza, there are three different types of users - normal users (typically students), administrators, super administrators. A normal user can participate in a course or an assignment or both. Courses and assignments are different entities in the system which allow enrollment of users. While a course is an independent entity, an assignment is part of a course.

The participants controller manages the participants across these courses and assignments by providing functionalities like listing all participants, adding a participant to a course or an assignment, updating the authorizations of a participant (can_submit, can_review, can_take_quiz), deleting a participant, inheriting participants from a course to an assignment, bequeath assignment participants to the corresponding course, changing the handle name of a participant in an assignment, and deleting a participant from an assignment.

Implementation

As part of the re-implementation, the objective is to employ an API-first approach while maintaining all the existing functionality in an efficient, robust and simple manner. Specifically for the participants controller, we've added seven different API endpoints to extend the current functionalities while modifying the code to support these APIs. The details for these endpoints can be found below.

#	Method	Endpoint	Description
1	Index	GET /participants/index/:model/:id	Returns a list of participants of an assignment or a course
2	Create	POST /participants/:model/:id/:authorization	Creates a participant in an assignment or a course
3	Update Handle	POST /participants/change_handle/:id	Updates the participant's handle for an assignment
4	Update Authorizations	POST /participants/update_authorizations/:id/:authorization	Updates the participant's permissions for an assignment or a course depending on the role
5	Delete	DELETE /participants/:id	Deletes a participant from an assignment or a course
6	Inherit	GET /participants/inherit/:id	Copies existing participants from a course down to its assignment
7	Bequeath	GET /participants/bequeath/:id	Copies existing participants from an assignment up to its course

Index

Purpose: Returns a list of participants of an assignment or a course

Description: This endpoint allows the user to request a list of all participants for the provided assignment ID or course ID. A success response renders a JSON with a list of participants that can be parsed by the front-end.

Path: /participants/index/:model/:id

API method: GET

Parameters:

#	Parameter	Expected Value
1	model	One of these two strings: ['Assignment', 'Course']
2	id	The unique identifier for an assignment or a course depending on the value of :model

• Success response

{
  "model_object": model_object,
  "participants": participants,
}
status: :ok

• Failure response

{ 
  error: "Missing or invalid required parameters" 
}
status: :unprocessable_entity

Changes: <TBD>

Create

Purpose: Creates a participant in an assignment or a course

Description: This endpoint allows the user to create a new participant for the provided assignment ID or course ID. A success response renders a JSON with the participant details. The user is required to provide a valid username as well as the appropriate permissions for the new participant. These permissions are [can_submit, can_review, can_take_quiz]. Depending on whether the request is for an Assignment or a Course, a participant type is determined between an AssignmentParticipant or a CourseParticipant and an entry is made into the database accordingly.

Path: /participants/:model/:id/:authorization

API method: POST

Parameters:

#	Parameter	Expected Value
1	model	One of these two strings: ['Assignment', 'Course']
2	id	The unique identifier for an assignment or a course depending on the value of :model
3	username	The unique username of the new participant being requested
4	authorization	A list of required permissions for the requested new particpant

Response:

• Success response

{
  "participant": participant,
}
status: :created

• Failure responses

When user does not exist

{ 
  error: "User #{params[:user][:name]} does not exist" 
}
status: :not_found

When participant already exists in the assignment/course

{ 
  error: "Participant #{params[:user][:name]} already exists for this #{params[:model]}" 
}
status: :unprocessable_entity

Changes: <TBD>

Update Handle

Purpose: Updates the participant's handle for an assignment

Description: This endpoint allows the user to change their handle name for a given AssignmentParticipant. An AssignmentParticipant is one who is already enrolled in the assignment. A success response renders a JSON with the updated participant details. The user is required to provide a valid and available handle name.

Path: /participants/change_handle/:id

API method: POST

Parameters:

#	Parameter	Expected Value
1	id	The unique identifier for an AssignmentParticipant
2	handle	A valid, available handle name for the participant

Response:

• Success responses

When handle change was successful

{
  "participant": participant,
}
status: :ok

When handle is already in use

{ 
  note: "Handle already in use" 
}
status: :ok

• Failure response

{ 
  error: participant.errors
}
status: :unprocessable_entity

Changes: <TBD>

Update authorizations

Purpose: Updates the participant's permissions for an assignment or a course depending on the role

Description: This endpoint allows the user to change the permissions for a given Participant. The appropriate permissions for any participant are [can_submit, can_review, can_take_quiz]. A Participant is one who is already enrolled in an assignment or a course. A success response renders a JSON with the updated participant details and permissions.

Path: /participants/update_authorizations/:id/:authorization

API method: POST

Parameters:

#	Parameter	Expected Value
1	id	The unique identifier for a Participant
2	authorization	A list of permissions being requested for the participant
3	can_submit	A value for whether the participant can make submissions or not.
4	can_review	A value for whether the participant can create reviews or not.
5	can_take_quiz	A value for whether the participant can take quizzes or not.

Response:

• Success response

{
  "participant": participant,
}
status: :ok

• Failure response

{ 
  error: participant.errors
}
status: :unprocessable_entity

Changes: <TBD>

Delete

Purpose: Deletes a participant from an assignment or a course

Description: This endpoint allows the user to delete an existing participant from an assignment or a course. The user is expected to provide the valid participant ID. The participant is only deleted if they are not part of another team for a different assignment/course. This is to ensure that a participant enrolled in two different teams is not deleted from the list of participants. Deletion is only possible if the participant is only enrolled in only one team. A success response renders a JSON with a confirmation of the deletion.

Path: /participants/:id

API method: DELETE

Parameters:

#	Parameter	Expected Value
1	id	The unique identifier for a Participant

Response:

• Success response

{
  message: "#{participant.user.name} was successfully removed as a participant"
}
status: :ok

• Failure responses

When the participant is on another team

{ 
  error: "This participant is on a team" 
}
status: :unprocessable_entity

{ 
  error: "Failed to remove participant" 
}
status: :unprocessable_entity

Changes: <TBD>

Inherit

Purpose: Copies existing participants from a course down to its assignment

Description: This endpoint allows the user to copy the existing participants from a course to the provided assignment in a single operation. Before this is carried out, validations are performed on 1) the existence of a course for the provided assignment and 2) non-empty list of participants already registered in the course. After these checks, the participants are copied from the course to the given assignment. A success response renders a JSON with a confirmation of the copy.

Path: /participants/inherit/:id

API method: GET

Parameters:

#	Parameter	Expected Value
1	id	The unique identifier for an Assignment

Response:

• Success responses

When copy was successful

{
  message: "The participants from #{source.name} were copied to #{target.name}"
}
status: :created

When all the participants already existed in the assignment(no-op)

{
  note: "All of #{source.name} participants are already in #{target.name}"
}
status: :ok

When there were no participants for the course

{
  note: "No participants were found for this #{source.name}"
}
status: :ok

• Failure response

When there is no course for the given assignment

{ 
  error: "No course was found for this assignment"
}
status: :unprocessable_entity

Changes: <TBD>

Bequeath

Purpose: Copies existing participants from an assignment up to its course

Description: This endpoint allows the user to copy the existing participants from the provided assignment to its associated course in a single operation. Before this is carried out, validations are performed on 1) the existence of a course for the provided assignment and 2) non-empty list of participants already registered in the assignment. After these checks, the participants are copied from the given assignment to its course. A success response renders a JSON with a confirmation of the copy.

Path: /participants/bequeath/:id

API method: GET

Parameters:

#	Parameter	Expected Value
1	id	The unique identifier for an Assignment

Response:

• Success responses

When copy was successful

{
  message: "The participants from #{source.name} were copied to #{target.name}"
}
status: :created

When all the participants already existed in the course(no-op)

{
  note: "All of #{source.name} participants are already in #{target.name}"
}
status: :ok

When there were no participants for the assignment

{
  note: "No participants were found for this #{source.name}"
}
status: :ok

• Failure response

When there is no course for the given assignment

{ 
  error: "No course was found for this assignment"
}
status: :unprocessable_entity

Changes: <TBD>

Test Plan

<TBD>

Contributors

1. Saksham Pandey (spandey5@ncsu.edu)
2. Devashish Vachhani (dvachha@ncsu.edu)
3. Karthik K Jayakumar (kkunnum@ncsu.edu)

Mentor: Rucha Kolekar (rbkoleka@ncsu.edu)

Relevant Links

• Github Repository for new code: https://github.com/devashish-vachhani/reimplementation-back-end
• Github Repository for old code: https://github.com/expertiza/expertiza/blob/main/app/controllers/participants_controller.rb
• Pull Request: https://github.com/expertiza/reimplementation-back-end/pull/22
• VCL Server: http://152.7.176.119