Pearson
Always Learning

This API allows you to manage the custom categories in a course. A custom category is any string of text against which a grade can be recorded. (Note, a category must be associated with a unit to create a gradable item before a grade can be saved.)

Note: Custom category names must be unique. If you attempt to create a category with a duplicate name you'll get an HTTP Error Code in response.



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{.format}
  • Retrieve all custom categories created in the course.
GET /courses/{courseId}/gradebook/customCategories/{categoryGuid}{.format}
  • Retrieve a specific custom category.
POST /courses/{courseId}/gradebook/customCategories{.format}
  • Create a new custom category.
PUT /courses/{courseId}/gradebook/customCategories/{categoryGuid}{.format}
  • Update a specific custom category.
DELETE /courses/{courseId}/gradebook/customCategories/{categoryGuid}{.format}
  • Delete a specific custom category.

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
{.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 and PUT Requests

{
    "customCategories": {
        "title": "{title}",
        "isAssignable": {isAssignableFlag}
    }
}

Property Descriptions


Name Description Valid Values
{title} Title of the category to show in the gradebook. Arbitrary string. Must be unique to the course.
{isAssignableFlag} This property is optional (and defaults to false). If you create a category that is assignable, it will appear in the LearningStudio Gradebook User Interface with no items or points possible. However, this field is optional because once you create the custom category (which is required to save a grade for this category), this flag flips to true.
  • true
  • false

Query String Parameters

No Query String Parameters are supported.

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.

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

When updating or 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

{
  "customCategories": [
    {
      "guid":"{categoryGuid}",
      "title": "{title}",
      "isAssignable": {isAssignableFlag}
    },
    {
      "guid":"{categoryGuid}",
      "title": "{title}",
      "isAssignable": {isAssignableFlag}
    }
  ]
}

Note: When requesting a single category (see Endpoints, above) or when creating a category, the payload is similar but the top-level property is singular (customCategory) and its value is an object rather than array.

Property Descriptions

Name Description
{categoryGuid} LearningStudio Custom Category GUID. Note this is in GUID format and is not an integer ID as used in other areas of LearningStudio.
{title} Title of the category to show in the gradebook.
{isAssignableFlag} Designates whether this custom category is assignable, meaning it has been added to the gradebook with a custom item and can be graded. Value is boolean, either true or false.

Example: Create or Update Custom Category

Request

Endpoint for Creating

POST /courses/123456/gradebook/customCategories

Endpoint for Updating

PUT /courses/123456/gradebook/customCategories/fc45af7e-ffeb-4444-ABCD-a63fcd34c216

Body

{
    "customCategories": {
        "title": "My Custom Item",
        "isAssignable": true
    }
}

Response

HTTP Header

Location: https://api.learningstudio.com/courses/123456/gradebook/customCategories/fc45af7e-ffeb-4444-ABCD-a63fcd34c216

Body

{
  "customCategory": {
	"guid":"fc45af7e-ffeb-4444-ABCD-a63fcd34c216",
    "title": "My Custom Item",
    "isAssignable": true
  }
}

Example: Get All Custom Categories for Course

Request

Endpoint

GET /courses/123456/gradebook/customCategories

Response

Body

{
  "customCategories":[        
    {
      "guid":"86554cab-0759-4388-aef1-5ac01ac275ce",
      "title":"Homework",
      "isAssignable":true
    },
    {
      "guid":"37254cfe-0779-2184-aef1-8ac0dacb75c3",
      "title":"Field Trip",
      "isAssignable":true
    }
  ]
}
2975 reads
Always Learning
Pearson