Pearson
Always Learning

For a custom category (as well as default category) to be gradable, it must be attached to a unit to create a custom gradable item. This API allows you to retrieve the custom items for a category, create a new one, or delete one.

Note: You will need to retrieve a unit ID from the Content Structure APIs.



Supported Roles and Authentication Protocols

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

API Request

API Endpoints

HTTP Verbs and URIs

GET /courses/{courseId}/gradebook/customCategories/{categoryGuid}/customItems{.format}
  • Retrieve all custom items for a custom category.
GET /courses/{courseId}/gradebook/customCategories/{categoryGuid}/customItems/{customItemGuid}{.format}
  • Retrieve a single custom item.
POST /courses/{courseId}/gradebook/customCategories/{categoryGuid}/customItems{.format}
  • Create a new custom item for a custom category.
DELETE /courses/{courseId}/gradebook/customCategories/{categoryGuid}/customItems/{customItemGuid}{.format}
  • Delete a custom item.

Parameters

Parameter Description Valid Values
{courseId} LearningStudio Course ID or relevant course overload.
  • Numeric ID issued by LearningStudio
  • ccn={callNumber}
{categoryGuid} LearningStudio Custom Category GUID. Note this is in GUID format and is not an integer ID as used in other areas of LearningStudio. String GUID issued by LearningStudio
{customItemGuid} LearningStudio Custom Gradable Item GUID. Note this is in GUID format and is not an integer ID as used in other areas of LearningStudio. String GUID issued by LearningStudio
{.format} Desired format of response data. See Response Formats. .json , .xml , or Blank

Query String Parameters

No query string parameters are supported.

Request Body

For GET and DELETE Requests

None

For POST Requests

{
  "customItem":{
    "unitId":{unitId},
    "isIncludedInGrade":{isIncludedInGradeFlag},
    "isExtraCredit":{isExtraCreditFlag},
    "pointsPossible":{pointsPossible}
  }
}

Property Descriptions

Property Descriptions

Name Description Valid Values
{unitId} Content Item ID for the unit. Numeric ID assigned by LearningStudio. Note, Unit IDs start with "200".
{isIncludedInGradeFlag} Designates whether the grades entered in this item affect the course total grade.
  • true
  • false
{isExtraCreditFlag} Designates whether the grades entered in this item are counted as extra credit. If it's extra credit, the points awarded here increase the student's achieved points but the points possible value is not added to the course's total points possible. The item must be included in the grade (see previous property) to be assignable as extra credit.
  • true
  • false
{pointsPossible} The total possible points that can be awarded for this item. Any float (decimal) number or integer.

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.

Note: When creating an item, the API will return a Location header, providing the location of the new category. See this page for more about this header.

When deleting a category, the API will return a status code of 204 - No Content with no response body. When creating a category, a status code of 201 - Created is returned along with a response body.

Response Body

Format

{
  "customItems":[
  {
    "guid":"{customItemGuid}",
    "customCategoryGuid":"{customCategoryGuid}",
    "unitId":{unitId},
    "links":[
    {
      "href":"{itemHref}",
      "rel":"http://api.learningstudio.com/rels/course/item"
    },{
      "href":"{categoryHref}",
      "rel":"http://api.learningstudio.com/rels/course/gradebook/customCategory"
    },{
     	"href":"{gradebookItemHref}",
      	"rel":"https://api.learningstudio.com/rels/course/gradebook/gradebookItem"
    }]
  }
  ]
}

Property Descriptions

Name Description
{customItemGuid} LearningStudio Custom Gradable Item GUID. Note this is in GUID format and is not an integer ID as used in other areas of LearningStudio.
{customCategoryGuid} LearningStudio Custom Category GUID. Note this is in GUID format and is not an integer ID as used in other areas of LearningStudio.
{unitId} LearningStudio Content Item ID for the Unit
{itemHref} A link to content item detail (e.g., title)
{categoryHref} A link to custom category detail (e.g., title).
{gradebookItemHref} A link to an API that returns another link to the gradable item detail for this custom item. You can also use the {customItemGuid} directly in that API (see next section).

Custom Items and Gradable Items

This API returns the information related setting up a gradable item (i.e., associating it with a custom category and unit), but does not return the information related to grading. The Gradable Items API provides that information such as points possible, whether the item is included in the course total, etc. The two APIs can be thought of as two perspectives of the same object.

To get the gradable item detail for a custom item, simply use the same identifying GUID (referred to as {customItemGuid} below), in the Gradable Items API. For example, this API's endpoint is:

/courses/{courseId}/gradebook/customCategories/{categoryGuid}/customItems/{customItemGuid}

and this endpoint will give you the gradable item detail for the same object:

/courses/{courseId}/gradebook/gradebookItems/{customItemGuid}

The Gradable Items API also returns custom items in its results when requesting all gradable items in a course.

Example: Get All Gradable Items for a Custom Category

Request

Endpoint

GET /courses/123456/gradebook/customCategories/fc45af7e-ffeb-4be5-a9a7-a63fcd34c216/customItems

Response

Body

{
  "customItems":[{
    "guid":"77ba449b-1234-FFFF-ZZZZ-ABCDEFGHIJKL",
    "customCategoryGuid":"fc45af7e-FFBB-FFBB-FFBB-a63fcd34c216",
    "unitId":200816102,
    "links":[{
      	"href":"https://api.learningstudio.com/courses/2022657/items/200816102",
      	"rel":"https://api.learningstudio.com/rels/course/item"
      },{
      	"href":"https://api.learningstudio.com/courses/2022657/gradebook/customCategories/fc45af7e-FFBB-FFBB-FFBB-a63fcd34c216",
      	"rel":"https://api.learningstudio.com/rels/course/gradebook/customCategory"
      },{
     	"href":"https://api.learningstudio.com/courses/2022657/gradebook/customCategories/fc45af7e-FFBB-FFBB-FFBB-a63fcd34c216/customItems/77ba449b-1234-FFFF-ZZZZ-ABCDEFGHIJKL/gradebookItem",
      	"rel":"https://api.learningstudio.com/rels/course/gradebook/gradebookItem"
      }]
  },{
    "guid":"77ba449b-ABCD-1234-XYZA-123456789000",
    "customCategoryGuid":"fc45af7e-FFBB-FFBB-FFBB-a63fcd34c216",
    "unitId":200816102,
    "links":[{
      	"href":"https://api.learningstudio.com/courses/2022657/items/200816102",
      	"rel":"https://api.learningstudio.com/rels/course/item"
      },{
      	"href":"https://api.learningstudio.com/courses/2022657/gradebook/customCategories/fc45af7e-FFBB-FFBB-FFBB-a63fcd34c216",
      	"rel":"https://api.learningstudio.com/rels/course/gradebook/customCategory"
      },{
     	"href":"https://api.learningstudio.com/courses/2022657/gradebook/customCategories/fc45af7e-FFBB-FFBB-FFBB-a63fcd34c216/customItems/77ba449b-ABCD-1234-XYZA-123456789000/gradebookItem",
      	"rel":"https://api.learningstudio.com/rels/course/gradebook/gradebookItem"
      }]
  }]
}

Example: Create Custom Item for a Custom Category

Request

Endpoint

POST /courses/123456/gradebook/customCategories/fc45af7e-ffeb-4be5-a9a7-a63fcd34c216/customItems

Body

{
  "customItem":{
    "unitId":2001234567,
    "isIncludedInGrade":true,
    "isExtraCredit":false,
    "pointsPossible":100
  }
}

Response

HTTP Headers

Location: https://api.learningstudio.com/courses/123456/gradebook/customCategories/fc45af7e-ABCD-1234-a9a7-ABCDEFGJIL/customItems/86554cab-ABCD-EFGJ-HIKL-123456789000

Body

{
  "customItem":{
    "guid":"86554cab-ABCD-EFGJ-HIKL-123456789000",
    "customCategoryGuid":"fc45af7e-ABCD-1234-a9a7-ABCDEFGJIL",
    "unitId":2001234567,
    "links":[
    {
      "href":"https://api.learningstudio.com/courses/123456/items/2001234567",
      "rel":"https://api.learningstudio.com/rels/course/item"
    },
    {
      "href":"https://api.learningstudio.com/courses/123456/gradebook/customCategories/fc45af7e-ABCD-1234-a9a7-ABCDEFGJIL",
      "rel":"https://api.learningstudio.com/rels/course/gradebook/customCategory"
    },
    {
      "href":"https://api.learningstudio.com/courses/123456/gradebook/customCategories/fc45af7e-ABCD-1234-a9a7-ABCDEFGJIL/customItems/86554cab-ABCD-EFGJ-HIKL-123456789000/gradebookItem",
      "rel":"https://api.learningstudio.com/rels/course/gradebook/gradebookItem"
    }
    ]
  }
}
3367 reads
Always Learning
Pearson