Query options in Learn365 API: overview and usage

Introduction

When using API endpoints, an API request is sent to a server (resource) and, after it is processed, the server returns a response back to the client—Learn365—with the information retrieved or function performed. The amount and order of the data returned to Learn365 in the response can be controlled in Swagger by a set of query string parameters—system query options.

This article describes the system query options of the Learn365 API and gives guidance on how to use these.

 

Query options

Overview

API requests can be used to manage courses and training plans and their materials, get statistics on users and training, add, remove, enroll in and unenroll users from training and much more.

Depending on the amount of data of a tenant, some API requests can heavily load your tenant which will cause slow report generating, increase time of load page, and even slow loading. All this can be prevented by controlling the response data returned which is done with the help of system query options parameters. 

System query options are query string parameters that control the amount and order of the data returned for the resource identified by the URL. The names of all system query options are prefixed with a dollar ($) character. The system query options are:

• $expand
• $filter
• $select
• $orderby
• $top
• $skip
• $count

 

For the query options parameters the default data of the values can be of the following types:

• guid - The unique id associated with the shared parameter.
• string - any finite sequence of characters (letters, numerals, symbols, punctuation marks, etc.).
• integer - whole number.
• boolean - true or false variable.

 

$expand

The $expand system query option allows clients to return related entries with a single URL— the related resources or media streams will be included in line with retrieved resources.

Entities that it is possible to expand can be seen in the property's Model under the Responses block or in the Models at the bottom of the Learn365 API sections list.

You can expand a property that is nested inside another property. Query options can be applied to an expanded navigation property by appending a semicolon-separated list of query options, enclosed in parentheses, to the navigation property name. Allowed system query options are $filter, $select, $orderby, $skip, $top, $count, $search, and $expand. You can find details on filter specification here.

 

 

Examples

An example of a property used for the $expand query option of the Courses section can be: Quizzes.

 

 

In this particular case, in the response you will get the data about each quiz included in each course of the tenant. You can download the results in the .JSON file format to your computer.

 

 

An example of request with a property that is nested inside another property can be the GET /odata/v2/Courses request from the Courses section: expand the Course property in the Model > expand the Quizzes property inside the Course property > Sharing. So, the value in the $expand will be: Quizzes($expand=Sharing)

 

 

In this particular case, in the response you will get the data related to the sharing settings of each quiz of each course of the tenant. You can download the results in the .JSON file format to your computer.

 

 

$filter

The $filter system query option allows clients to filter a collection of resources that are addressed by a request URL and to have a response returned with the items that meet the condition only. You can also filter by a property that is nested inside another property. You can find details on filter specification here.

A set of non-selectable and non-filterable API properties that can't be used for $filter can be found here.

 

Examples

An example of a nested $filter can be the GET /odata/v2/Courses request from the Courses section: for the $filter set as 'IsPublished eq true' , where IsPublished indicates the parameter to filter by, eq is an equals operator and true is a filter value. 

 

 

In this case the response will contain the data on the published courses of the tenant only.

 

 

It is possible to add filter by expanded properties got from the Model of the relevant section as well. First in the $expand state what Model part the filter will be applied to and then in the $filter set the filtering parameter.

For example, for the GET /odata/v2/Enrollments request from the Enrollments section, we will set Course for $expand to add data about courses and training plans to the response. Then we will set the filtering parameter for $filter as Course/CourseType eq 'TrainingPlan', where CourseType indicates the parameter to filter by, eq is an equals operator and select 'TrainingPlan' is a filter value. The results in the response will be filtered by the training type to show only the training plans from all the courses catalogs of the tenant.

 

 

$select

Use the $select option to specify the exact properties (each entity or complex type) you want to include in the response.

The $select query option is often used in conjunction with the $expand system query option, to define the extent of the resource graph to return ($expand) and then specify a subset of properties for each resource in the graph ($select).

You can find details on filter specification here.

A set of non-selectable and non-filterable API properties that can't be used for $select can be found here.

 

Example

For example, if you use 'Title' for the $select query for the GET /odata/v2/Competencies (skills) from the Competencies (skills) section, the response will include the results only matching this parameter - the titles of the skills of the entire tenant. 

 

 

An example of a combination of $select and $expand can be the following request: if you use Title for the $select for the GET /odata/v2/Competencies (skills) from the Competencies (skills) section and set Course for $expand. 

 

 

In this case the response will contain the title of the skill and data about the courses this skill is granted for.

 

 

$orderby

The $orderby system query option allows clients to request resources in a particular order. You can find details on filter specification here.

Related entities may be ordered by specifying $orderby within the $expand clause.

 

Examples

For example, using RegistrationDate desc for $orderby in the GET /odata/v2/Enrollments request from the Enrollments section, you will get the response where all courses from the tenant are ordered by the descending registration date. 

 

 

An example of a combination of $orderby and $expand can be the same GET /odata/v2/Enrollments request: Course for $expand and Course/CEU desc for $orderby. In this case the response body will display courses ordered by the descending number of CEUs they grant.

 

 

Also, $count is quite often used within a $orderby expression to order the returned items according to the exact count of related entities or items within a collection-valued property.

Let's use both $count and $orderby for the GET /odata/v2/Enrollments request from the Enrollments section: set RegistrationDate desc for $orderby and select true for $count. 

 

 

In the results, the response will show us not only the training ordered by the  descending number of CEUs they grant but the amount of courses and training plans with CEUs will be counted and displayed in the beginning of the response.

 

 

$top

The $top system query option allows clients to get a response with the first n results included. Fill in the field with a whole number and you will get the corresponding number of returns included in the response. 

Also, $top is particularly helpful when used with the $orderby option.

You can find details on filter specification here.

 

Examples

For example, we can set $top as 15 for the GET /odata/v2/CourseCatalogs request from the CourseCatalogs section. In this case the request will show us the first 15 course catalogs of the tenant.

 

 

An example of a combination of $top and $orderby can be the GET /odata/v2/Enrollments request from the Enrollments section: Title for $orderby and 10 for $top. In this case the response body will display the first 10 course catalogs of the tenant ordered by the title.

 

 

A client can request a particular page of items by combining $top and $skip.

 

$skip

The $skip query option allows clients to get a response with the first x results skipped. Fill in the field with a whole number and you will get the response with the the corresponding number of first returns skipped. 

You can find details on filter specification here.

 

Examples

For example, we can set $skip as 20 for the GET /odata/v2/CourseCatalogs request from the CourseCatalogs section. In this case the request will show course catalogs of the tenant with the first 20 results skipped.

 

 

$skip is particularly helpful when used with the $orderby and/or in combination with the $top option.

For example, with $orderby set as Course/CEU desc, $top set as 15 and $skip set as 20, the response will contain top 15 courses ordered by the descending CEUs they grant by skipping the first 20 results. 

 

 

$count

The $count system query option allows clients to request a count of the matching resources included with the resources in the response. The $count query option has a Boolean value of true or false.

 

The response will be presented as count: number of the matching results, for example

 "@odata.count": 50

You can find details on filter specification here.

 

Any and all

When you use expand for properties that won’t return the single value, but collection, then any/all operators should be used to filter on collection fields. Both must be prepended with a navigation path that identifies a collection. 

• The any operator applies a Boolean expression to each member of a collection and returns true if and only if the expression is true for any member of the collection, otherwise it returns false.  This implies that the any operator always returns false for an empty collection. The any operator can be used without an argument expression.

• The all operator applies a Boolean expression to each member of a collection and returns true if the expression is true for all members of the collection, otherwise it returns false. This implies that the all operator always returns true for an empty collection. The all operator cannot be used without an argument expression.

Find more detailed information here.

 

Query options usage

Go to Swagger and get authorized, then scroll down to the Learn365 API block and find the relevant section and method.

We will show query options usage on the example of an API request from the Enrollments section.

We will use the GET request /odata/v2/Enrollments with the Returns the list of current user's active Enrollments description.

 

 

To continue, select the Try it out option, enter the query parameters and select the Execute button to run the request. For our example we set these parameters that will  provide us data (including users' ID, registration date and registration status) on the top 15 active courses (with the 20 first results skipped) and these courses will be ordered by the users' registration date descending.

 

 

Scroll to go to the Responses block to check the results:

• Number 2xx (for example, 200) under Code shows that the request worked correctly.
• The Response body field will display the data according to the properties set. You can use search via Ctrl+F to find the relevant data.