Applications: Using the REST API

The ClassLink OneRoster API is a tool for searching data from uploaded CSVs.

Overview

Getting to the API
Using the API to Search for Data
Narrowing Down the Search Results
Dealing with {id}

Getting to the API

To quickly view the data available to an app, open the actions menu on the app you want to view -> click Explore in API.

By default, the 1.1 endpoints are shown. If you wish to see the 1.0 endpoints, select it from the dropdown menu at the top and click Explore.

Using the API to Search for Data

Each endpoint corresponds to a matching CSV file.

In other words:

ims/oneroster/v1p1/academicSessions has data from the academicSessions.csv file
ims/oneroster/v1p1/classes has data from the classes.csv file
ims/oneroster/v1p1/courses has data from the courses.csv file
ims/oneroster/v1p1/demographics has data from the demographics.csv file
ims/oneroster/v1p1/enrollments has data from the enrollments.csv file
ims/oneroster/v1p1/orgs has data from the orgs.csv file
ims/oneroster/v1p1/resources has data from the resources.csv file
ims/oneroster/v1p1/users has data from the users.csv file

You will notice that there are several text fields. Fields, Filter, Limit, Offset and Sort are all filtering tools, but if you don't want to filter the data, click Try it out! without typing anything in the text fields.

Note: By default, the first 100 data records will be returned.

Scroll down to the Response Body. Data is in JSON format, where academicSessions is an array and each row in the CSV is a JavaScript object. Column field headers become the properties of the objects. In this case, academic Sessions has field headers: sourcedId, status, dateLastModified, title, startDate, endDate, type, children, and schoolYear. In JavaScript Object Notation, these become the object's properties.

Scroll down to Response Headers to view more information about the data. x-total-count is the total number of records.

Narrowing Down the Search Results

Searching by fields will return only the selected field(s) of each record. For example, if you wanted to search by type AND title AND status, you would input the following in the fields box:

type,title,status

Searching by filter will return the records that have the desired value for the filtered object property. Example:

type='semester'

Changing the number for limit will restrict the number of results displayed below. If you only want the first ten search results, then make sure to change the default of 100 to 10.

Note: There is a maximum limit of 10000 for API requests.

orderBy asc or desc will order the results by the property in the sort field in either ascending or descending order.

This is the result of the above query:

Dealing with {id}

Under Roster, you will see a number of endpoints that have {id} in their titles. These only have one search factor: sourcedId.

ims/oneroster/v1p1/academicSessions/{id}

ims/oneroster/v1p1/classes/{id}

ims/oneroster/v1p1/courses/{id}

ims/oneroster/v1p1/demographics/{id}

ims/oneroster/v1p1/enrollments/{id}

ims/oneroster/v1p1/orgs/{id}

ims/oneroster/v1p1/resources/{id}

ims/oneroster/v1p1/users/{id}

For example, inputting a sourcedId from ims/oneroster/v1p1/academicSessions into ims/oneroster/v1p1/academicSessions/{id} will display JUST that one data point.

In cases such as /ims/oneroster/v1p1/schools/{id}/enrollments, a valid school sourcedId will produce a list of that school's enrollments.

Another example, /ims/oneroster/v1p1/schools/{school_id}/classes/{class_id}/students needs a sourcedId from /ims/oneroster/v1p1/orgs, and a sourcedId from /ims/oneroster/v1p1/schools/{id}/classes.

Note: Make sure to input a sourcedId from "/ims/oneroster/v1p1/orgs" into the endpoint: "/ims/oneroster/v1p1/schools/{id}/classes" so that you know the class sourcedId you provide for /ims/oneroster/v1p1/schools/{school_id}/classes/{class_id}/students is compatible. (i.e. make sure that the class is taught at that particular school.)

The query comes back with all students from that particular school attending that particular class.

Updated: Mar 2020

Articles in this section