CSC/ECE 517 Spring 2023 E2318: Reimplement Participants Controller: Difference between revisions

Revision as of 21:31, 27 March 2023

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 two different models: Course and Assignment. Although an Assignment is a part of a Course, students can participate in a Course or an Assignment independently.

The ParticipantsController provides functionalities for listing the participants of a course or an assignment, adding a participant to a course or an assignment, updating the authorizations of a participant (can_submit, can_review, can_take_quiz), updating the handle of a participant for an assignment, inheriting course participants to its assignment, bequeathing assignment participants to its course and deleting a participant from a course or an assignment.

Project Goals

Reimplement the Expertiza Participants Controller as a Rails API while maintaining the existing functionality of the controller.

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.

Assumptions

The participants model has the method team which checks the existence of a participant on another team. This functionality is used as a pre-check for deletion of a participant.
The course participant and assignment participant models have the copy method which would be used to copy a list of participants from the course/assignment to the assingment/course. This functionality is used to support the inherit and bequeath functionalities.

API documentation

#	Method	Endpoint	Description
1	index	GET `/participants/:model/:id`	returns a list of participants of an assignment or a course
2	create	POST `/participants/:model/:id`	creates a participant in an assignment or a course
3	update_handle	PATCH `/participants/change_handle/:id`	updates the participant's handle for an assignment
4	update_authorizations	PATCH `/participants/update_authorizations/:id`	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

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: GET /participants/:model/:id

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`

Response:

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

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

Create

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: POST /participants/:model/:id

Request Body:

content:
  application/json:
    schema:
      type: object
      properties:
        user:
          type: object
          properties:
          name: string
        participant:
          type: object
          properties:
        can_submit:
          type: boolean
        can_review:
          type: boolean
        can_take_quiz:
          type: boolean

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
{
  "participant": participant,
}
status: :created

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

Update Handle

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: POST /participants/change_handle/:id

Request Body:

content:
  application/json:
    schema:
      type: object
      properties:
        participant:
          type: object
          properties:
          handle: 
            type: integer

Parameters:

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

Response:

When handle change was successful
{
  "participant": participant,
}
status: :ok

When handle is already in use
{ 
  note: "Handle already in use" 
}
status: :ok

Failure
{ 
  error: participant.errors
}
status: :unprocessable_entity

Update authorizations

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: POST /participants/update_authorizations/:id

Request Body:

content:
  application/json:
    schema:
      type: object
      properties:
        participant:
          type: object
          properties:
            can_submit:
              type: boolean
            can_review:
              type: boolean
            can_take_quiz:
              type: boolean

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
{
  "participant": participant,
}
status: :ok

Failure
{ 
  error: participant.errors
}
status: :unprocessable_entity

Delete

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: DELETE /participants/:id

Parameters:

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

Response:

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

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

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

Inherit

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 with the help of a private method copy_participants_from_source_to_target. A success response renders a JSON with a confirmation of the copy.

Path: GET /participants/inherit/:id

Parameters:

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

Response:

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

When there is no course for the given assignment
{ 
  error: "No course was found for this assignment"
}
status: :unprocessable_entity

Bequeath

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 with the help of a private method copy_participants_from_source_to_target. A success response renders a JSON with a confirmation of the copy.

Path: GET /participants/bequeath/:id

Parameters:

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

Response:

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

When there is no course for the given assignment
{ 
  error: "No course was found for this assignment"
}
status: :unprocessable_entity

Test Plan

Since Expertiza has been originally tested with RSpec, we have continued to use RSpec to test out model. The participants_controller.rb depends on many methods and associations with other models. To test the methods in the participants controller, we have stubbed some of these dependent methods. To progress with our testing, we've added the associations in the respective sample model files since these were necessary for stubbing.

To run the tests, kindly pull from the repository and run bundle install to install the necessary dependencies. Once done, please run rspec participants_controller_spec.rb. Once the tests have run, a swagger.yml can be generated by running the command rails swag:specs:swaggerize

Tests

Test ID	Test Description
1	Test to check index with Assignment model and id
2	Test to check index with Course model and id
3	Test to check index with a non-existent id
4	Test to create a new participant
5	Test to confirm update handle request for a participant
6	Test to verify failure of an update handle request for a participant
7	Test to update authorizations for a participant
8	Test to verify failure of an update authorizations request for a participant
9	Test to inherit participants from a Course to an Assignment
10	Test to verify failure for inherit participants from a Course to an Assignment when course had no participants
11	Test to inherit participants from an Assignment to a Course
12	Test to verify failure for inherit participants from an Assignment to a Course when assignment had no participants
13	Test to destroy a participant
14	Test to verify failure of destroying a participant
15	Test to verify denying the destroy method for a participant who is on another team
16	<TBD>

Swagger

Contributors

Saksham Pandey (spandey5@ncsu.edu)
Devashish Vachhani (dvachha@ncsu.edu)
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
Testing video: https://drive.google.com/file/d/1gR6adaEzAyWWg3z_s-aPbaxE2cscXDlP/view?ts=641f6906
VCL Server: http://152.7.176.119

@@ Line 9: / Line 9: @@
 == Project Goals ==
-Reimplement the expertiza ParticipantsController as a Rails API while maintaining the existing functionality of the ParticipantsController.
+Reimplement the Expertiza Participants Controller as a Rails API while maintaining the existing functionality of the controller.
 == 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.
+=== Assumptions ===
+#The participants model has the method <code>team</code> which checks the existence of a participant on another team. This functionality is used as a pre-check for deletion of a participant.
+#The course participant and assignment participant models have the <code>copy</code> method which would be used to copy a list of participants from the course/assignment to the assingment/course. This functionality is used to support the inherit and bequeath functionalities.
 ----
 === API documentation ===
@@ Line 56: / Line 62: @@
 ==== 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''': GET <code>/participants/index/:model/:id</code>
+'''Path''': GET <code>/participants/:model/:id</code>
 '''Parameters''':
@@ Line 92: / Line 96: @@
 ==== 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 <code>[can_submit, can_review, can_take_quiz]</code>. Depending on whether the request is for an <code>Assignment</code> or a <code>Course</code>, a participant type is determined between an <code>AssignmentParticipant</code> or a <code>CourseParticipant</code> and an entry is made into the database accordingly.
-'''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 <code>[can_submit, can_review, can_take_quiz]</code>. Depending on whether the request is for an <code>Assignment</code> or a <code>Course</code>, a participant type is determined between an <code>AssignmentParticipant</code> or a <code>CourseParticipant</code> and an entry is made into the database accordingly.
+'''Path''': POST <code>/participants/:model/:id</code>
-'''Path''': POST <code>/participants/:model/:id/:authorization</code>
+'''Request Body''':
+<pre>
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        user:
+          type: object
+          properties:
+          name: string
+        participant:
+          type: object
+          properties:
+        can_submit:
+          type: boolean
+        can_review:
+          type: boolean
+        can_take_quiz:
+          type: boolean
+</pre>
 '''Parameters''':
@@ Line 141: / Line 165: @@
 ==== 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 <code>AssignmentParticipant</code>. An <code>AssignmentParticipant</code> 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''': POST <code>/participants/change_handle/:id</code>
+'''Request Body''':
+<pre>
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        participant:
+          type: object
+          properties:
+          handle:
+            type: integer
+</pre>
 '''Parameters''':
@@ Line 183: / Line 219: @@
 ==== 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 <code>Participant</code>. The appropriate permissions for any participant are <code>[can_submit, can_review, can_take_quiz]</code>. A <code>Participant</code> 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.
-'''Description''': This endpoint allows the user to change the permissions for a given <code>Participant</code>. The appropriate permissions for any participant are <code>[can_submit, can_review, can_take_quiz]</code>. A <code>Participant</code> 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''': POST <code>/participants/update_authorizations/:id</code>
-'''Path''': POST <code>/participants/update_authorizations/:id/:authorization</code>
+'''Request Body''':
+<pre>
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        participant:
+          type: object
+          properties:
+            can_submit:
+              type: boolean
+            can_review:
+              type: boolean
+            can_take_quiz:
+              type: boolean
+</pre>
 '''Parameters''':
@@ Line 231: / Line 283: @@
 ==== 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.
@@ Line 269: / Line 319: @@
 ==== 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 with the help of a private method <code>copy_participants_from_source_to_target</code>. A success response renders a JSON with a confirmation of the copy.
-'''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''': GET <code>/participants/inherit/:id</code>
@@ Line 313: / Line 361: @@
 ==== 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 with the help of a private method <code>copy_participants_from_source_to_target</code>. A success response renders a JSON with a confirmation of the copy.
-'''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''': GET <code>/participants/bequeath/:id</code>
@@ Line 355: / Line 401: @@
 status: :unprocessable_entity
 </pre>
-----
-=== Assumptions ===
-<TBD>
 == Test Plan ==
@@ Line 365: / Line 407: @@
 To run the tests, kindly pull from the [https://github.com/devashish-vachhani/reimplementation-back-end/ repository] and run bundle install to install the necessary dependencies. Once done, please run <code>rspec participants_controller_spec.rb</code>.
+Once the tests have run, a <code>swagger.yml</code> can be generated by running the command <code>rails swag:specs:swaggerize</code>
 ====Tests====
@@ Line 401: / Line 444: @@
 |-
 | 15 || Test to verify denying the destroy method for a participant who is on another team
+|-
+| 16 || <TBD>
 |}
+==== Swagger ====
+<Insert screenshot here>

CSC/ECE 517 Spring 2023 E2318: Reimplement Participants Controller: Difference between revisions

Revision as of 21:31, 27 March 2023

Contents

Introduction

Background

Project Goals

Implementation

Assumptions

API documentation

Index

Create

Update Handle

Update authorizations

Delete

Inherit

Bequeath

Test Plan

Tests

Swagger

Contributors

Relevant Links

Navigation menu

CSC/ECE 517 Spring 2023 E2318: Reimplement Participants Controller: Difference between revisions

Revision as of 21:31, 27 March 2023

Introduction

Background

Project Goals

Implementation

Assumptions

API documentation

Index

Create

Update Handle

Update authorizations

Delete

Inherit

Bequeath

Test Plan

Tests

Swagger

Contributors

Relevant Links

Navigation menu

Search