lms.djangoapps.grades.rest_api.v1 package

Submodules

lms.djangoapps.grades.rest_api.v1.gradebook_views module

Defines an endpoint for gradebook data related to a course.

class lms.djangoapps.grades.rest_api.v1.gradebook_views.BaseCourseView(**kwargs)

Bases: DeveloperErrorViewMixin, GenericAPIView

A base class for course info APIs. TODO: https://openedx.atlassian.net/browse/EDUCATOR-3755 This whole thing is duplicated from cms/djangoapps/contentstore

authentication_classes = (<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'openedx.core.lib.api.authentication.BearerAuthenticationAllowInactiveUser'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>)

get_course(request, course_key)

Context manager that yields a course, given a request and course_key.

permission_classes = (<class 'rest_framework.permissions.IsAuthenticated'>,)

class lms.djangoapps.grades.rest_api.v1.gradebook_views.CourseGradingView(**kwargs)

Bases: BaseCourseView

Returns information about assignments and assignment types for a course. Example Requests

GET /api/grades/v1/gradebook/{course_id}/grading-info

GET Parameters

A GET request may include the following parameters.

• graded_only (boolean) - If true, only returns subsection data for graded subsections (defaults to False).

GET Response Values

The HTTP 200 response has the following values.

• assignment_types - A dictionary keyed by the assignment type name with the following values:

  • min_count - The minimum number of required assignments of this type.

  • weight - The weight assigned to this assignment type for course grading.

  • type - The name of the assignment type.

  • drop_count - The maximum number of assignments of this type that can be dropped.

  • short_label - The short label prefix used for short labels of assignments of this type (e.g. ‘HW’).

• subsections - A list of subsections contained in this course.

  • module_id - The string version of this subsection’s location.

  • display_name - The display name of this subsection.

  • graded - Boolean indicating whether this subsection is graded (for at least one user in the course).

  • short_label - A short label for graded assignments (e.g. ‘HW 01’).

  • assignment_type - The assignment type of this subsection (for graded assignments only).

can_see_bulk_management(course_key)

Whether or not to show bulk management for this course. Currently, if a course has a master’s track or is enabled with the grades.bulk_management course waffle flag.

get(request, course_id, *args, **kwargs)

Checks for course author access for the given course by the requesting user. Calls the view function if has access, otherwise raises a 403.

class lms.djangoapps.grades.rest_api.v1.gradebook_views.GradebookBulkUpdateView(**kwargs)

Bases: GradeViewMixin, PaginatedAPIView

Use Case

Creates PersistentSubsectionGradeOverride objects for multiple (user_id, usage_id) pairs in a given course, and invokes a Django signal to update subsection grades in an asynchronous celery task.

Example Request

POST /api/grades/v1/gradebook/{course_id}/bulk-update

POST Parameters

This endpoint does not accept any URL parameters.

Example POST Data

[

{

“user_id”: 9, “usage_id”: “block-v1:edX+DemoX+Demo_Course+type@sequential+block@basic_questions”, “grade”: {

“earned_all_override”: 11, “possible_all_override”: 11, “earned_graded_override”: 11, “possible_graded_override”: 11, “comment”: “reason for override”

}

}, {

“user_id”: 9, “usage_id”: “block-v1:edX+DemoX+Demo_Course+type@sequential+block@advanced_questions”, “grade”: {

“earned_all_override”: 10, “possible_all_override”: 15, “earned_graded_override”: 9, “possible_graded_override”: 12, “comment”: “reason for override”

}

}

]

POST Response Values

An HTTP 202 may be returned if a grade override was created for each of the requested (user_id, usage_id) pairs in the request data. An HTTP 403 may be returned if the writable_gradebook feature is not enabled for this course. An HTTP 404 may be returned for the following reasons:

• The requested course_key is invalid.

• No course corresponding to the requested key exists.

• The requesting user is not enrolled in the requested course.

An HTTP 422 may be returned if any of the requested (user_id, usage_id) pairs did not have a grade override created due to some exception. A reason detailing the exception is provided with each response item.

Example successful POST Response

[

{

“user_id”: 9, “usage_id”: “some-requested-usage-id”, “success”: true, “reason”: null

}, {

“user_id”: 9, “usage_id”: “an-invalid-usage-id”, “success”: false, “reason”: “<class ‘opaque_keys.edx.locator.BlockUsageLocator’>: not-a-valid-usage-key”

}, {

“user_id”: 9, “usage_id”: “a-valid-usage-key-that-doesn’t-exist”, “success”: false, “reason”: “a-valid-usage-key-that-doesn’t-exist does not exist in this course”

}, {

“user_id”: 1234-I-DO-NOT-EXIST, “usage_id”: “a-valid-usage-key”, “success”: false, “reason”: “User matching query does not exist.”

}

]

authentication_classes = (<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'openedx.core.lib.api.authentication.BearerAuthenticationAllowInactiveUser'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>)

permission_classes = (<class 'rest_framework.permissions.IsAuthenticated'>,)

post(request, course_id, *args, **kwargs)

Checks for course author access for the given course by the requesting user. Calls the view function if has access, otherwise raises a 403.

class lms.djangoapps.grades.rest_api.v1.gradebook_views.GradebookUpdateResponseItem(user_id, usage_id, success, reason)

Bases: tuple

reason

Alias for field number 3

success

Alias for field number 2

usage_id

Alias for field number 1

user_id

Alias for field number 0

class lms.djangoapps.grades.rest_api.v1.gradebook_views.GradebookView(**kwargs)

Bases: GradeViewMixin, PaginatedAPIView

Use Case

• Get course gradebook entries of a single user in a course,

or of all users who are actively enrolled in a course. The currently logged-in user may request all enrolled user’s grades information if they are allowed.

Example Request

GET /api/grades/v1/gradebook/{course_id}/ - Get gradebook entries for all users in course GET /api/grades/v1/gradebook/{course_id}/?username={username} - Get grades for specific user in course GET /api/grades/v1/gradebook/{course_id}/?username={username}?history_record_limit={number}

• Get grades for specific user in course, only show {number} latest records

GET /api/grades/v1/gradebook/{course_id}/?user_contains={user_contains} GET /api/grades/v1/gradebook/{course_id}/?username_contains={username_contains} GET /api/grades/v1/gradebook/{course_id}/?cohort_id={cohort_id} GET /api/grades/v1/gradebook/{course_id}/?enrollment_mode={enrollment_mode}

GET Parameters

A GET request may include the following query parameters. * username: (optional) A string representation of a user’s username. * user_contains: (optional) A substring against which a case-insensitive substring filter will be performed

on the USER_MODEL.username, or the USER_MODEL.email, or the PROGRAM_ENROLLMENT.external_user_key fields.

• username_contains: (optional) A substring against which a case-insensitive substring filter will be performed on the USER_MODEL.username field.

• cohort_id: (optional) The id of a cohort in this course. If present, will return grades only for course enrollees who belong to that cohort.

• enrollment_mode: (optional) The slug of an enrollment mode (e.g. “verified”). If present, will return grades only for course enrollees with the given enrollment mode.

GET Response Values

If the request for gradebook data is successful, an HTTP 200 “OK” response is returned. The HTTP 200 response for a single has the following values: * course_id: A string representation of a Course ID. * email: A string representation of a user’s email. * user_id: The user’s integer id. * username: A string representation of a user’s username passed in the request. * full_name: A string representation of the user’s full name. * passed: Boolean representing whether the course has been

passed according to the course’s grading policy.

• percent: A float representing the overall grade for the course

• progress_page_url: A link to the user’s progress page.

• section_breakdown: A list of subsection grade details, as specified below.

A response for all user’s grades in the course is paginated, and contains “count”, “next” and “previous” keys, along with the actual data contained in a “results” list.

An HTTP 404 may be returned for the following reasons:

• The requested course_key is invalid.

• No course corresponding to the requested key exists.

• No user corresponding to the requested username exists.

• The requested user is not enrolled in the requested course.

An HTTP 403 may be returned if the writable_gradebook feature is not enabled for this course.

Example GET Response

{

“user_id”: 9, “username”: “staff”, “percent”: 0.36, “section_breakdown”: [

{

“are_grades_published”: true, “auto_grade”: false, “category”: null, “chapter_name”: “Introduction”, “comment”: “”, “detail”: “”, “displayed_value”: “0.00”, “grade_description”: “(0.00/0.00)”, “is_ag”: false, “is_average”: false, “is_manually_graded”: false, “label”: null, “module_id”: “block-v1:edX+DemoX+Demo_Course+type@sequential+block@edx_introduction”, “percent”: 0.0, “score_earned”: 0.0, “score_possible”: 0.0, “section_block_id”: “block-v1:edX+DemoX+Demo_Course+type@chapter+block@abcdefgh123”, “subsection_name”: “Demo Course Overview”

},

],

}

Paginated GET response

When requesting gradebook entries for all users, the response is paginated and contains the following values: * next: The URL containing the next page of data. * previous: The URL containing the previous page of data. * results: A list of user gradebook entries, structured as above. * total_users_count: The total number of active users in the course. * filtered_users_count: The total number of active users that match

the filter associated with the provided query parameters.

Note: It’s important that GradeViewMixin is the first inherited class here, so that self.api_error returns error responses as expected.

authentication_classes = (<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'openedx.core.lib.api.authentication.BearerAuthenticationAllowInactiveUser'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>)

get(request, course_id, *args, **kwargs)

Checks for course author access for the given course by the requesting user. Calls the view function if has access, otherwise raises a 403.

pagination_class

alias of CourseEnrollmentPagination

permission_classes = (<class 'rest_framework.permissions.IsAuthenticated'>,)

class lms.djangoapps.grades.rest_api.v1.gradebook_views.SubsectionGradeView(**kwargs)

Bases: GradeViewMixin, APIView

Use Case

• This api is to get information about a users original grade for a subsection.

It also exposes any overrides that now replace the original grade and a history of user changes with time stamps of all changes.

Example Request

GET /api/grades/v1/subsection/{subsection_id}/?user_id={user_id}

GET Parameters

A GET request may include the following query parameters. * user_id: (required) An integer represenation of a user

GET Response Values

If the request for subsection grade data is successful, an HTTP 200 “OK” response is returned. The HTTP 200 response has the following values: * subsection_id: A string representation of the usage_key for a course subsection * user_id: The user’s integer id * course_id: A string representation of a Course ID. * original_grade: An object representation of a users original grade containing:

• earned_all: The float score a user earned for all graded and not graded problems

• possible_all: The float highest score a user can earn for all graded and not graded problems

• earned_graded: The float score a user earned for only graded probles

• possible_graded: The float highest score a user can earn for only graded problems

• override: An object representation of an over ride for a user’s subsection grade containing:

  • earned_all_override: The float overriden score a user earned for all graded and not graded problems

  • possible_all_override: The float overriden highest score a user can earn for all graded and not graded problems

  • earned_graded_override: The float overriden grade a user earned for only graded problems

  • possible_graded_override: The float overriden highest possible grade a user can earn for only graded problems

• history: A list of history objects that contain

  • user: The string representation of the user who was responsible for overriding the grade

  • comments: A string comment about why that person changed the grade

  • created: The date timestamp the grade was changed

  • feature: The string representation of the feature through which the grade was overrriden

  • action: The string representation of the CRUD action the override did

An HTTP 404 may be returned for the following reasons:

• The requested subsection_id is invalid.

• The requested user_id is invalid.

• NOTE: if you pass in a valid subsection_id and a valid user_id with no data representation in the DB then you will still recieve a 200 with a response with ‘original_grade’, ‘override’ and ‘course_id’ set to None and the ‘history’ list will be empty.

Example GET Response

{

“subsection_id”: “block-v1:edX+DemoX+Demo_Course+type@sequential+block@basic_questions”, “user_id”: 2, “course_id”: “course-v1:edX+DemoX+Demo_Course”, “original_grade”: {

“earned_all”: 0, “possible_all”: 11, “earned_graded”: 8, “possible_graded”: 11

}, “override”: {

“earned_all_override”: null, “possible_all_override”: null, “earned_graded_override”: 8, “possible_graded_override”: null

}, “history”: [

{

“user”: “edx”, “comments”: null, “created”: “2018-12-03T18:52:36.087134Z”, “feature”: “GRADEBOOK”, “action”: “CREATEORUPDATE”

}, {

“user”: “edx”, “comments”: null, “created”: “2018-12-03T20:41:02.507685Z”, “feature”: “GRADEBOOK”, “action”: “CREATEORUPDATE”

}, {

“user”: “edx”, “comments”: null, “created”: “2018-12-03T20:46:08.933387Z”, “feature”: “GRADEBOOK”, “action”: “CREATEORUPDATE”

}

]

}

authentication_classes = (<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'openedx.core.lib.api.authentication.BearerAuthenticationAllowInactiveUser'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>)

get(request, subsection_id)

Returns subection grade data, override grade data and a history of changes made to a specific users specific subsection grade.

Parameters:

• subsection_id – String representation of a usage_key, which is an opaque key of

• grade. (a persistant subection)

• user_id – An integer represenation of a user

permission_classes = (<class 'rest_framework.permissions.IsAuthenticated'>,)

exception lms.djangoapps.grades.rest_api.v1.gradebook_views.SubsectionUnavailableToUserException

Bases: Exception

lms.djangoapps.grades.rest_api.v1.gradebook_views.bulk_gradebook_view_context(course_key, users)

Prefetches all course and subsection grades in the given course for the given list of users, also, fetch all the score relavant data, storing the result in a RequestCache and deleting grades on context exit.

lms.djangoapps.grades.rest_api.v1.gradebook_views.course_author_access_required(view)

Ensure the user making the API request has course author access to the given course.

This decorator parses the course_id parameter, checks course access, and passes the parsed course_key to the view as a parameter. It will raise a 403 error if the user does not have author access.

Usage::

@course_author_access_required def my_view(request, course_key):

# Some functionality …

lms.djangoapps.grades.rest_api.v1.gradebook_views.get_bool_param(request, param_name, default)

Given a request, parameter name, and default value, returns either a boolean value or the default.

lms.djangoapps.grades.rest_api.v1.gradebook_views.verify_writable_gradebook_enabled(view_func)

A decorator to wrap a view function that takes course_key as a parameter.

Raises:

A 403 API error if the writable gradebook feature is not enabled for the given course. –

lms.djangoapps.grades.rest_api.v1.urls module

Grades API v1 URLs.

lms.djangoapps.grades.rest_api.v1.utils module

Define some view level utility functions here that multiple view modules will share

class lms.djangoapps.grades.rest_api.v1.utils.CourseEnrollmentPagination

Bases: CursorPagination

Paginates over CourseEnrollment objects.

get_page_size(request)

Get the page size based on the defined page size parameter if defined.

get_paginated_response(data, status_code=200, **kwargs)

Return a response given serialized page data, optional status_code (defaults to 200), and kwargs. Each key-value pair of kwargs is added to the response data.

ordering = 'id'

page_size = 50

page_size_query_param = 'page_size'

class lms.djangoapps.grades.rest_api.v1.utils.GradeViewMixin

Bases: DeveloperErrorViewMixin

Mixin class for Grades related views.

perform_authentication(request)

Ensures that the user is authenticated (e.g. not an AnonymousUser).

lms.djangoapps.grades.rest_api.v1.views module

API v0 views.

class lms.djangoapps.grades.rest_api.v1.views.CourseGradesView(**kwargs)

Bases: GradeViewMixin, PaginatedAPIView

Use Case

• Get course grades of all users who are enrolled in a course.

The currently logged-in user may request all enrolled user’s grades information if they are allowed.

Example Request

GET /api/grades/v1/courses/{course_id}/ - Get grades for all users in course GET /api/grades/v1/courses/{course_id}/?username={username} - Get grades for specific user in course GET /api/grades/v1/courses/?course_id={course_id} - Get grades for all users in course GET /api/grades/v1/courses/?course_id={course_id}&username={username}- Get grades for specific user in course

GET Parameters

A GET request may include the following parameters. * course_id: (required) A string representation of a Course ID. * username: (optional) A string representation of a user’s username.

GET Response Values

If the request for information about the course grade is successful, an HTTP 200 “OK” response is returned. The HTTP 200 response has the following values. * username: A string representation of a user’s username passed in the request. * email: A string representation of a user’s email. * course_id: A string representation of a Course ID. * passed: Boolean representing whether the course has been

passed according to the course’s grading policy.

• percent: A float representing the overall grade for the course

• letter_grade: A letter grade as defined in grading policy (e.g. ‘A’ ‘B’ ‘C’ for 6.002x) or None

Example GET Response

[{

“username”: “bob”, “email”: “bob@example.com”, “course_id”: “course-v1:edX+DemoX+Demo_Course”, “passed”: false, “percent”: 0.03, “letter_grade”: null,

}, {

“username”: “fred”, “email”: “fred@example.com”, “course_id”: “course-v1:edX+DemoX+Demo_Course”, “passed”: true, “percent”: 0.83, “letter_grade”: “B”,

}, {

“username”: “kate”, “email”: “kate@example.com”, “course_id”: “course-v1:edX+DemoX+Demo_Course”, “passed”: false, “percent”: 0.19, “letter_grade”: null,

}]

authentication_classes = (<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'openedx.core.lib.api.authentication.BearerAuthenticationAllowInactiveUser'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>)

get(request, course_id=None)

Gets a course progress status. :param request: Django request object. :type request: Request :param course_id: URI element specifying the course location.

Can also be passed as a GET parameter instead.

Returns:

A JSON serialized representation of the requesting user’s current grade status.

pagination_class

alias of CourseEnrollmentPagination

permission_classes = (<rest_framework.permissions.OperandHolder object>,)

required_scopes = ['grades:read']

class lms.djangoapps.grades.rest_api.v1.views.CourseGradingPolicy(**kwargs)

Bases: GradeViewMixin, ListAPIView

Use Case

Get the course grading policy.

Example requests:

GET /api/grades/v1/policy/courses/{course_id}/

Response Values

• assignment_type: The type of the assignment, as configured by course staff. For example, course staff might make the assignment types Homework, Quiz, and Exam.

• count: The number of assignments of the type.

• dropped: Number of assignments of the type that are dropped.

• weight: The weight, or effect, of the assignment type on the learner’s final grade.

allow_empty = False

authentication_classes = (<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'openedx.core.lib.api.authentication.BearerAuthenticationAllowInactiveUser'>, <class 'edx_rest_framework_extensions.auth.session.authentication.SessionAuthenticationAllowInactiveUser'>)

get(request, course_id, *args, **kwargs)

class lms.djangoapps.grades.rest_api.v1.views.SectionGradesBreakdown(**kwargs)

Bases: GradeViewMixin, PaginatedAPIView

Section grades breakdown gives out the overall grade for a user in a course accompanied by grades for each section of the course for the user.

authentication_classes = (<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'edx_rest_framework_extensions.auth.bearer.authentication.BearerAuthentication'>, <class 'rest_framework.authentication.SessionAuthentication'>)

get(request)

Use Cases

Get a list of all grades for all sections, optionally filtered by a course ID or list of usernames.

Example Requests

GET /api/grades/v1/section_grades_breakdown

GET /api/grades/v1/section_grades_breakdown?course_id={course_id}

GET /api/grades/v1/section_grades_breakdown?username={username},{username},{username}

GET /api/grades/v1/section_grades_breakdown?course_id={course_id}&username={username}

Query Parameters for GET

• course_id: Filters the result to course grade status for the course corresponding to the

  given course ID. The value must be URL encoded. Optional.

• username: List of comma-separated usernames. Filters the result to the course grade status

  of the given users. Optional.

• page_size: Number of results to return per page. Optional.

Response Values

If the request for information about the course grade status is successful, an HTTP 200 “OK” response is returned.

The HTTP 200 response has the following values.

• results: A list of the course grading status matching the request.

  • course_id: Course ID of the course in the course grading status.

  • user: Username of the user in the course enrollment.

  • passed: Boolean flag for user passing the course.

  • current_grade: An integer representing the current grade of the course.

  • section_breakdown: A summary of each course section’s grade.

  A dictionary in the section_breakdown list has the following keys:

  • percent: A float percentage for the section.

  • label: A short string identifying the section. Preferably fixed-length. E.g. “HW 3”.

  • detail: A string explanation of the score. E.g. “Homework 1 - Ohms Law - 83% (5/6)”

  • category: A string identifying the category.

  • prominent: A boolean value indicating that this section should be displayed as more prominent

    than other items.

• next: The URL to the next page of results, or null if this is the

  last page.

• previous: The URL to the next page of results, or null if this

  is the first page.

If the user is not logged in, a 401 error is returned.

If the user is not global staff, a 403 error is returned.

If the specified course_id is not valid or any of the specified usernames are not valid, a 400 error is returned.

If the specified course_id does not correspond to a valid course or if all the specified usernames do not correspond to valid users, an HTTP 200 “OK” response is returned with an empty ‘results’ field.

pagination_class

alias of CourseEnrollmentPagination

permission_classes = (<class 'edx_rest_framework_extensions.permissions.IsStaff'>,)

class lms.djangoapps.grades.rest_api.v1.views.SubmissionHistoryView(**kwargs)

Bases: GradeViewMixin, PaginatedAPIView

Submission history corresponding to ProblemBlocks present in the course.

authentication_classes = (<class 'edx_rest_framework_extensions.auth.jwt.authentication.JwtAuthentication'>, <class 'edx_rest_framework_extensions.auth.bearer.authentication.BearerAuthentication'>, <class 'rest_framework.authentication.SessionAuthentication'>)

check_throttles(request)

Check if request should be throttled. Raises an appropriate exception if the request is throttled.

get(request, course_id=None)

Get submission history details. This submission history is related to only ProblemBlock and it doesn’t support LegacyLibraryContentBlock or ContentLibraries as of now.

Usecases:

Users with GlobalStaff status can retrieve everyone’s submission history.

Example Requests:

GET /api/grades/v1/submission_history/{course_id} GET /api/grades/v1/submission_history/{course_id}/?username={username}

Query Parameters for GET

• course_id: Course id to retrieve submission history.

• username: Single username for which this view will retrieve the submission history details.

Response Values:

If there’s an error while getting the submission history an empty response will be returned. The submission history response has the following attributes:

• Results: A list of submission history:

  • course_id: Course id

  • course_name: Course name

  • user: Username

  • problems: List of problems

    • location: problem location

    • name: problem’s display name

    • submission_history: List of submission history

      • state: State of submission.

      • grade: Grade.

      • max_grade: Maximum possible grade.

    • data: problem’s data.

static get_problem_blocks(course)

Get a list of problem xblock for the course. This doesn’t support LegacyLibraryContentBlock or ContentLibraries as of now

pagination_class

alias of CourseEnrollmentPagination

permission_classes = (<class 'edx_rest_framework_extensions.permissions.IsStaff'>,)

throttle_classes = (<class 'openedx.core.djangoapps.enrollments.views.EnrollmentUserThrottle'>,)

lms.djangoapps.grades.rest_api.v1.views.bulk_course_grade_context(course_key, users)

Prefetches grades for the given users in the given course within a context, storing in a RequestCache and deleting on context exit.

Module contents