Grades API

Grades API

gradereport_overview_get_course_grades

This function retrieves an overview of all final course grades for a specific user.

Let's review the POST parameters for this function:

  1. Optional Parameter:
    • userid= int (Optional: The numeric ID of the user. If omitted, it returns grades for the user associated with the API token.)

cURL Command Example (Getting a User's Course Grades):

curl "https://courses.yoursite.com/webservice/rest/server.php?wstoken=XXXXXXXXXXXXXXX" \
-d "wsfunction=gradereport_overview_get_course_grades" \
-d "userid=123"


core_grades_update_grades

This function updates the grade for a specific activity (like an assignment or quiz) for one or more students.

Let's review the POST parameters for this function:

  1. Required Parameters:
    • source= string (Required: A string identifying the source of the grade update, e.g., 'externalimporter'.)
    • courseid= int (Required: The numeric ID of the course.)
    • component= string (Required: The component type, e.g., 'mod_assign' for an assignment.)
    • activityid= int (Required: The numeric ID of the specific activity instance.)
    • itemnumber= int (Required: The grade item index, which is typically 0.)
    • grades[0][studentid]= int (Required: The numeric ID of the student being graded.)
    • grades[0][grade]= double (Required: The numeric grade to be assigned.)
  2. Optional Parameter:
    • grades[0][str_feedback]= string (Optional: Text-based feedback for the student.)

cURL Command Example (Updating a Student's Grade):

curl "https://courses.yoursite.com/webservice/rest/server.php?wstoken=XXXXXXXXXXXXXXX" \
-d "wsfunction=core_grades_update_grades" \
-d "source=externalimporter" \
-d "courseid=789" \
-d "component=mod_assign" \
-d "activityid=45" \
-d "itemnumber=0" \
-d "grades[0][studentid]=123" \
-d "grades[0][grade]=85.5" \
-d "grades[0][str_feedback]=Excellent work on the final submission."


mod_assign_get_grades

This function retrieves all student grades for one or more specific assignments.

Let's review the POST parameters for this function:

  1. Required Parameter:
    • assignmentids[0]= int (Required: The numeric ID of an assignment. Pass multiple to get grades for several assignments.)
  2. Optional Parameter:
    • since= int (Optional: A Unix timestamp to filter for grades that were modified after this time.)

cURL Command Example (Getting Assignment Grades):

curl "https://courses.yoursite.com/webservice/rest/server.php?wstoken=XXXXXXXXXXXXXXX" \
-d "wsfunction=mod_assign_get_grades" \
-d "assignmentids[0]=45"


mod_quiz_get_user_best_grade

This function retrieves the highest grade a user has achieved on a specific quiz.

Let's review the POST parameters for this function:

  1. Required Parameter:
    • quizid= int (Required: The numeric ID of the quiz instance.)
  2. Optional Parameter:
    • userid= int (Optional: The numeric ID of the user. If omitted, it checks the user associated with the API token.)

cURL Command Example (Getting a User's Best Quiz Grade):

curl "https://courses.yoursite.com/webservice/rest/server.php?wstoken=XXXXXXXXXXXXXXX" \
-d "wsfunction=mod_quiz_get_user_best_grade" \
-d "quizid=99" \
-d "userid=123"