Pearson
Always Learning

Some resources allow you to optionally filter or refine the response data based on various query parameters. This topic provides general information on the use of the query parameters. Individual API documentation pages list which query parameters are supported for that API request.

Query parameters are optional and can be used singly or combined. To use a query parameter, you append a question mark ( ? ) to the resource endpoint (after the optional {.format} parameter) followed by the desired query parameter. Multiple query parameters are used in combination ("AND" processing). To use multiple query parameters, you separate them with an ampersand ( & ).

For example, the following request returns events scheduled between March 1, 2013 and April 17, 2013:

/users/2117707/upcomingevents?since=03/01/2013&until=04/17/2013

Supported Query Parameters

Here are the query string parameters that you will encounter in LearningStudio APIs. Not all APIs support all parameters; refer to the documentation for each API.

Name Description Syntax
after The date after which to retrieve the results. after={MM/DD/YYYY}
before The date before which to retrieve the results. before={MM/DD/YYYY}
courseid The LearningStudio course ID for which to return the results. courseid={courseId}
depth The number of levels to traverse when retrieving responses. depth={integer}
excludeInactive Whether to include only active results in the response. excludeInactive=true|false
expand Return detailed data for resources within the response. See below. expand={title}
includeAllTerms Whether to include results from the entire history of courses (in all terms, past and present) in which the user has been enrolled. includeAllTerms=true|false
includeContentDisposition Whether to include the content disposition information for a dropbox attachment. includeContentDisposition=true|false
includeFutureTerms Whether to include results only for the current term or for the current term and all future terms in which the user is enrolled. includeFutureTerms=true|false
includeInherited Whether to include events whose scheduled dates are inherited from the parent item. includeInherited=true|false
limit The number of results to retrieve. limit={limitNumber}
markedAsRead Whether to mark the data item as read once this request is made. markedasread=true|false
offset The start index of the retrieved results. offset={offsetNumber}
since The start date of the date range at which to begin returning the results. since={MM/DD/YYYY}
sortBy The data used to control the sort order of the returned results. Order is always in ascending order. sortby={sortData}
submissionStudent The user ID of the student who submitted the dropbox item. submissionStudent={userId}
types The course item type of the results to be returned. Can be a single value or multiple. If multiple, values must be separated by commas. types={courseItemType}
until The end date of the date range at which to limit the results. until={MM/DD/YYYY}
useSourceDomain Whether to return the fully qualified URL for any content or to truncate it to remove the domain. useSourceDomain=true|false
v The version of the API to use. v={version number}

Expand Parameter

The expand query parameter allows a collection to be expanded beyond the information about the resources requested. This allows you to retrieve more information about a resource using fewer queries. Many resources have relationships with other resources. For example, course items are contained in a hierarchy (Exams within a Unit, Units within a Course, and Courses within a Term). You can request a response collection containing information from base resources and also from related resources (link traversal).

Not all APIs support expansion. It's most common in the Content APIs. Refer to the specific API reference for each API.

Link Expansion

Each item returned in an array includes an array of link objects that connect the item to its related resources. For example:

"links" : [ 
  { 
    "href" : "https://{domain}/courses/{courseId}/items/{itemId}/access",
    "rel" : "related", 
    "title" : "access"
  }

See Response Formats for an explanation of the difference between href and rel.

You can use the expand query string for embedded resources that have a title attribute. For example: GET /courses/123456/items/200654321/items?expand={title}, where {title} is the value of the title property of the link you want to expand. If you want to expand more than one property, you set the expand query string value to a comma-separated string of titles: GET /courses/123456/items/200654321/items?expand={title1,title2}.

In some cases, the expanded link may contain additional child links, which you can also expand using dot notation in the expand query parameter. Use a period between parent and child: GET /courses/123456/items/200654321/items?expand={title,title.childTitle}, where {childTitle} is the title exposed in the expanded {title}link.

Example: Expand Resource Properties

In this example, we retrieve the item information for a course and then use the expand query parameter to return the schedule information for each item in the course, using a single request.

Request (Without Expand Parameter)

GET /courses/123456/items/200654321/items

Response Body (Without Expanded Details)

{
  "items": [
    {
      "id": 100123456,
      "contentType": "HTML",
      "title": "Assignment 1",
      "links": [
        {
          "href": "https://{domain}/courses/123456/items/100123456/access",
          "rel": "related",
          "title": "access"
        },
        {
          "href": "https://{domain}/courses/123456/items/100123456/schedule",
          "rel": "related",
          "title": "schedule"
        }
      ]
    }
  ]
}

Notice that every item contains links to the access and schedule resources for that item, but no details on those elements other than the links. If you wanted to retrieve the access and/or schedule information of every item with one request, you would add the expand query parameter to your request. This example expands both access and schedule information.

Request (With Expand Parameter)

GET /courses/123456/items/200654321/items?expand=schedule,access

Response Body (With Expanded Details)

{
  "items": [
    {
      "id": 100123456,
      "contentType": "HTML",
      "title": "Assignment 1",
      "links": [
        {
          "href": "https://{domain}/courses/123456/items/100123456/access",
          "rel": "related",
          "title": "access"
        },
        {
          "href": "https://{domain}/courses/123456/items/100123456/schedule",
          "rel": "related",
          "title": "schedule",
          "schedule": {
            "dueDate": "2010-08-04T05:59:00Z",
            "startDateTime": "2010-08-02T06:00:00Z",
            "endDateTime": "2010-08-05T05:59:00Z"
          }
        }
      ]
    }
  ]
}

The access and schedule information is now available for each item. Note: In order to expand only a single property, such as schedule, the request would be: GET /courses/123456/items/200654321/items?expand=schedule.

Example: Expand Links within Links

In some cases, the expanded link may contain additional child links, which you can also expand using dot notation in the expand query parameter. In this example, we retrieve the item hierarchy information for a course and then use the expand query parameter to return the access and schedule information for each item within an item using a single request.

Request (Without Expand Parameter)

GET /courses/123456/itemhierarchy

Response Body (Without Expanded Details)

{
  "itemHierarchy": {
    "childItemNodes": [
      {
        "links": [
          {
            "href": "https://{domain}/courses/123456/items/200123456",
            "rel": "self",
            "title": "item"
          }
        ],
        "childItemNodes": [
          {
            "links": [
              {
                "href": "https://{domain}/courses/123456/items/200123457",
                "rel": "self",
                "title": "item"
              }
            ],
            "childItemNodes": []
          },
          {
            "links": [
              {
                "href": "https://{domain}/courses/123456/items/200123458",
                "rel": "self",
                "title": "item"
              }
            ],
              "childItemNodes": []
          }
        ]
      }
    ]
  }
}

Notice that each link within childItemNodes points to an item. You would use the expand query parameter to expand each item.

Request (With Expand Parameter)'

GET /courses/123456/itemhierarchy?expand=item

Response Body (With Expanded Details)

{
  "itemHierarchy": {
    "childItemNodes": [
      {
        "links": [
          {
            "href": "https://{domain}/courses/123456/items/200123456",
            "rel": "self",
            "title": "item",
            "item": {
              "id": 200123456,
              "contentType": "HTML",
              "title": "Module 1",
              "links": [
                {
                  "href": "https://{domain}/courses/123456/items/200123456/access",
                  "rel": "related",
                  "title": "access"
                },
                {
                  "href": "https://{domain}/courses/123456/items/200123456/schedule",
                  "rel": "related",
                  "title": "schedule"
                }
              ]
            }
          }
        ],
        "childItemNodes": [
          {
            "links": [
              {
                "href": "https://{domain}/courses/123456/items/200123457",
                "rel": "self",
                "title": "item",
                "item": {
                  "id": 200123457,
                  "contentType": "HTML",
                  "title": "Assignment 1",
                  "links": [
                    {
                      "href": "https://{domain}/courses/123456/items/200123457/access",
                      "rel": "related",
                      "title": "access"
                    },
                    {
                      "href": "https://{domain}/courses/123456/items/200123457/schedule",
                      "rel": "related",
                      "title": "schedule"
                    }
                  ]
                }
              }
            ],
            "childItemNodes": []
          },
        ]
      }
    ]
  }
}

Notice that every expanded item contains links to the access and <code>schedule resources for that item. If you wanted to retrieve the access and/or schedule information of every item with one request, you would use dot notation in the query string parameter to expand the child links. In this example we expand both access (item.access) and schedule (item.schedule) information.

Request (With Dot Notation in Expand Parameter)

GET /courses/123456/itemhierarchy?expand=item,item.access,item.schedule

Response (With Expanded Child Links)

{
  "itemHierarchy": {
    "childItemNodes": [
      {
        "links": [
          {
            "href": "https://{domain}/courses/123456/items/200123456",
            "rel": "self",
            "title": "item",
            "item": {
              "id": 200123456,
              "contentType": "HTML",
              "title": "Module 1",
              "links": [
                {
                  "href": "https://{domain}/courses/123456/items/200123456/access",
                  "rel": "related",
                  "title": "access"
                  "access": {
                    "canAccessBeforeStartDateTime": true,
                    "canAccessAfterEndDateTime": true
                  }
                },
                {
                  "href": "https://{domain}/courses/123456/items/200123456/schedule",
                  "rel": "related",
                  "title": "schedule"
                  "schedule": {
                    "dueDate": "2010-10-30T05:59:00Z",
                    "startDateTime": "2010-08-01T06:00:00Z",
                    "endDateTime": "2010-10-30T05:59:00Z"
                  }
                }
              ]
            }
          }
        ],
        "childItemNodes": [
          {
            "links": [
              {
                "href": "https://{domain}/courses/123456/items/200123457",
                "rel": "self",
                "title": "item",
                "item": {
                  "id": 200123457,
                  "contentType": "HTML",
                  "title": "Assignment 1",
                  "links": [
                    {
                      "href": "https://{domain}/courses/123456/items/200123457/access",
                      "rel": "related",
                      "title": "access"
                      "access": {
                        "canAccessBeforeStartDateTime":true,
                        "canAccessAfterEndDateTime": true
                      }
                    },
                    {
                      "href": "https://{domain}/courses/123456/items/200123457/schedule",
                      "rel": "related",
                      "title": "schedule"
                      "schedule": {
                        "dueDate": "2010-09-15T05:59:00Z",
                        "startDateTime": "2010-08-02T06:00:00Z",
                        "endDateTime": "2010-09-16T05:59:00Z"
                      }
                    }
                  ]
                }
              }
            ],
            "childItemNodes": []
          },
        ]
      }
    ]
  }
}

NOTE: ?expand=item,item.access and ?expand=item.access provide the exact same result. If you use item.access it implies that the parent must also be expanded, and therefore both item and item.access are expanded.

Requesting Unsupported Expansions

If you provide a value for the expand query parameter that is not valid (the expansion is not supported) you will receive a client error response, as shown in the following example.

Request

GET /courses/123456/itemhierarchy?expand=course

Response

HTTP/1.1 400 Bad Request

Response Body

{
  "error": {
    "message": "The requested expand value is not currently supported.",
    "request": "/courses/123456/itemhierarchy?expand=course"
  }
}
3175 reads
Always Learning
Pearson