Pearson
Always Learning

This API retrieves the gradebook structure (the full list of gradable items) specific to the perspective of a particular student. Compared to it's course-level counterpart which gives a generic view, this one includes only the items the specified student is being graded on (which can vary based on certain settings or group configuration). It also offers an expand query string parameter to retrieve a student's grade for the item.

Note: Unlike it's it's course-level counterpart this API does not support changing settings of gradable items.



Supported Roles and Authentication Protocols

Type Supported Values
Authentication Protocols OAuth 1.0a, OAuth 2.0
Valid for Roles (OAuth 2): Professor, Teaching Assistant, Student, Administrator

API Request

API Endpoints

HTTP Verbs and URIs

GET /users/{userId}/courses/{courseId}/gradebook/usergradebookItems{.format}
GET /users/{userId}/courses/{courseId}/usergradebookItems{.format}
  • Retrieve all of a student's gradable items.
  • These endpoints are synonymous.
GET /users/{userId}/courses/{courseId}/gradebook/usergradebookItems/{userGradebookItemId}{.format}
GET /users/{userId}/courses/{courseId}/usergradebookItems/{userGradebookItemId}{.format}
  • Retrieve a single gradable item for a student.
  • These endpoints are synonymous.

Parameters

Parameter Description Valid Values
{userId} LearningStudio User ID or relevant user overload.
  • Numeric ID issued by LearningStudio
  • loginid={clientString}|{username}
  • or replace /users/{userId} with /me
    (OAuth 2 only)
{courseId} LearningStudio Course ID or relevant course overload.
  • Numeric ID issued by LearningStudio
  • ccn={callNumber}
{userGradebookItemId} An API-specific ID for identifying a student's view of a gradable item. Essentially, it's a combination of the LearningStudio User ID and Gradable Item GUID. String identifier issued by LearningStudio
{.format} Desired format of response data. See Response Formats. .json , .xml , or Blank

Query String Parameters

Query Parameter Name Description Valid Values
expand By default the API will return a link to a student's grade object for each gradable item (if a grade exists and is enabled to share with student). This parameter opts to include the grade detail with the results of this API. grade or Blank

Request Body

None

API Response

Response HTTP Status Codes and Headers

This API returns the standard HTTP Status Codes used by the LearningStudio APIs. There are no special headers returned by the API.

Response Body

Format

{
  "userGradebookItems": [{
    "id": "{userGradebookItemId}",
    "gradebookItem": {
    	"type": "{gradebookItemType}",
      	"id": "{gradebookItemGuid}",
      	"title": "{gradebookItemTitle}",
      	"pointsPossible":{pointsPossible},
      	"weightsPossible":{weightsPossible},
      	"isIncludedInGrade":{isIncludedInGradeFlag},
      	"isExtraCredit":{isExtraCreditFlag},
      	"links": [{
           "href": "{contentItemHref}",
           "rel": "related"
      	},{
           "href":"{contentItemHref}",
           "rel":"https://api.learningstudio.com/courses/items/item"
      	},{
           "href":"{unitHref}",
           "rel":"https://api.learningstudio.com/courses/items/unit"
      	},{
          "href":"{dropboxBasketHref}",
          "rel":"https://api.learningstudio.com/course/dropboxbaskets"
      }]
    },
    "links": [{
       "href": "{gradeHref}",
       "rel": "http://api.learningstudio.com/rels/course/gradebookItem/grade",
       "title": "grade"
    }]
  }]
}

Property Descriptions

Name Description
{userGradebookItemId} AAn API-specific ID for identifying a student's view of a gradable item. Essentially, it's a combination of the LearningStudio User ID and Gradable Item GUID.
{gradebookItemType} Signifies whether the gradable item is for a default category or a custom category. Possible values are:

  • courseItem - default category
  • customItem - custom category
{gradebookItemGuid} LearningStudio Gradable Item GUID. Note this is in GUID format and is not an integer ID as used in other areas of LearningStudio.
{gradebookItemTitle} Title of the gradebook item.
{pointsPossible} Number of points the user will get for a correct answer on this item.
{weightsPossible} The "weight" of the course items relative to other course content, listed in percentage points. Weighting allows users to "count" some course content items more than others without having to rely on point totals.

Note: This property is only included in the payload if weighting is turned on for this gradebook (this is configured via the User Interface).

{isIncludedInGradeFlag} Boolean that defines whether the item is included in course grade calculations.
{isExtraCreditFlag} Boolean that defines whether the item is marked as extra credit.
{contentItemHref} A link to the detail for content item with which this gradable item is associated. (Due to the backwards-compatible evolution of this API over time, this URL may be duplicated in two separate links.) This may not appear for custom Items. Important: you should not parse this URL to find or store the IDs. Instead, use a GET request against this complete URL to retrieve the content item. Learn more.
{unitHref} A link to the detail for unit content item with which this gradable item is associated. Important: you should not parse this URL to find or store the IDs. Instead, use a GET request against this complete URL to retrieve the unit detail. Learn more.
{gradeHref} A link to the student's grade object for this gradable item. If no grade has been entered, this links property will be an empty array. Important: you should not parse this URL to find or store the IDs. Instead, use a GET request against this complete URL to retrieve the questions list. Learn more. You can also use the expand query string parameter to include the grade object here (see above).
{dropboxBasketHref} A link to the detail for dropbox basket content item with which this gradable item is associated. Important: you should not parse this URL to find or store the IDs. Instead, use a GET request against this complete URL to retrieve the unit detail. Learn more.

Example

This example includes the query string parameter for including the grade, if it exists.

Request

Endpoint

GET /users/888888/courses/123456/gradebook/userGradebookItems?expand=grade

Response

Body

{
  "userGradebookItems": [{
    "id": "888888-a24e4de6-ABCD-EFGH-1234-123456789000",
    "gradebookItem": {
      "type": "courseItem",
      "id": "a24e4de6-ABCD-EFGH-1234-123456789000",
      "title": "text item due yesterday",
      "pointsPossible":10.00,
      "isIncludedInGrade":true,
      "isExtraCredit":false,
      "links": [{
        "href": "https://api.learningstudio.com/courses/123456/items/1001234567",
        "rel": "related"
      },{
        "href":"https://api.learningstudio.com/courses/123456/items/1001234567",
        "rel":"https://api.learningstudio.com/courses/items/item"
      },{
        "href":"https://api.learningstudio.com/courses/123456/items/2007654321",
        "rel":"https://api.learningstudio.com/courses/items/unit"
      }]
    },
    "links": [ {
          "grade": {
            "id": 99988877766,
            "points": 11.25,
            "letterGrade": "",
            "comments": "",
            "shareWithStudent": true,
            "updatedDate": "2014-12-08T11:32:09Z",
            "gradedStudent": {
              "id": 888888,
              "links": [
                {
                  "href": "https://api.learningstudio.com/users/888888",
                  "rel": "self"
                }
              ]
            }
          },
          "href": "https://api.learningstudio.com/courses/123456/gradebookItems/a24e4de6-ABCD-EFGH-1234-123456789000/grades/99988877766",
          "rel": "https://api.learningstudio.com/rels/course/gradebookItem/grade",
          "title": "grade"
        }]
    },
    {
    "id": "888888-bd681b1c-FFFF-GGGG-HHHH-ABCDEFGHUJKL",
    "gradebookItem": {
      "type": "courseItem",
      "id": "bd681b1c-FFFF-GGGG-HHHH-ABCDEFGHUJKL",
      "title": "text item due today",
      "pointsPossible":10.00,
      "weightsPossible":12.00,
      "isIncludedInGrade":true,
      "isExtraCredit":false,
      "links": [{
        "href": "https://api.learningstudio.com/courses/123456/items/1001234567",
        "rel": "related"
      },{
        "href":"https://api.learningstudio.com/courses/123456/items/1001234567",
        "rel":"https://api.learningstudio.com/courses/items/item"
      },{
        "href":"https://api.learningstudio.com/courses/123456/items/2007654321",
        "rel":"https://api.learningstudio.com/courses/items/unit"
      },{
        "href":"https:/api.learningstudio.com/courses/123456/dropboxBaskets/7201",
        "rel":"https://api.learningstudio.com/course/dropboxbaskets"
      }]
    },
    "links": []
  }]
}
2970 reads
Always Learning
Pearson