OneRoster API
This article provides an overview of the OneRoster API schema.
In this article
OAuth 2 authorization - “Client credentials” grant
Revisions
|
Document Version |
Change Description |
Effective Date |
|
1.4 |
Gragebook attributes (GrandingPeriods, Categories, Results, LineItems) supported |
Jul 01, 2023 |
|
1.3 |
OneRoster API v1.0 is no longer supported |
Jul 01, 2019 |
|
1.2 |
‘primaryGrade’ attribute for Users moved to ‘gg4l.primaryGrade’ metadata extension |
Feb 27, 2019 |
|
1.1 |
'primarySchool' attribute added as extension to users for teacher and student roles |
Mar 11, 2019 |
|
1.0 |
Initial release |
Feb 15, 2019 |
OAuth 2 Authorization - “Client credentials” grant
Request:
The request for client credentials must contain WWW BASIC authorization with both the client_id and client secret key in the request header, such as: ‘Authorization’: ‘Basic {data}’, where data = Base64.encode(‘{client_id}:{client secret}’).
| POST | datahub/oauth/token | Endpoint for authenticating a client. |
| Parameter | Mode | Type | Description |
| grant_type | Required | String | The type of the response (should be: ‘client_credentials’) |
Example:
| Method | POST |
| URL | https://{hostname}/datahub/oauth/token |
| Body | grant_type=client_credentials |
| Headers | Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0 |
Response:
The API returns the following response on successful authentication:
{
"access_token": "zyx",
"token_type": "bearer",
"expires_in": 7199
}
|
Field |
Type |
Description |
|
access_token |
String |
OAuth 2.0 Access Token |
|
token_type |
String |
Token's type. Always ‘bearer’ |
|
expires_in |
Integer |
Expiration time in seconds |
|
scope |
String |
List of scopes that define data access level |
API Overview
The base path for OneRoster API v1.1 is /datahub/services/ims/oneroster/v1p1
Organizations
|
GET |
/orgs |
Retrieves a list of organizations you have access to |
|
GET |
/orgs/{id} |
Retrieves information of a specific organization |
Schools
|
GET |
/schools |
Retrieves a list of schools you have access to |
|
GET |
/schools/{id} |
Retrieves information of a specific schools |
AcademicSessions
|
GET |
/academicSessions |
Retrieves a list of academicSessions you have access to |
|
GET |
/academicSessions/{id} |
Retrieves information of a specific academicSessions |
Terms
|
GET |
/terms |
Retrieves a list of terms you have access to |
|
GET |
/terms/{id} |
Retrieves information of a specific terms |
Courses
|
GET |
/courses |
Gets a list of courses you have access to |
|
GET |
/courses/{id} |
Gets only a specific courses information |
|
GET |
/schools/{id}/courses |
Retrieves courses for schools |
Classes
|
GET |
/classes |
Gets a list of classes you have access to |
|
GET |
/classes/{id} |
Gets only a specific classes information |
|
GET |
/schools/{id}/classes |
Retrieves classes for schools |
|
GET |
/terms/{id}/classes |
Retrieves classes for terms |
|
GET |
/courses/{id}/classes |
Retrieves classes for a courses |
|
GET |
/students/{id}/classes |
Retrieves classes for students |
|
GET |
/teachers/{id}/classes |
Retrieves classes for teachers |
Users
|
GET |
/users |
Retrieves a list of users you have access to |
|
GET |
/users/{id} |
Retrieves information of specific users |
Demographics
|
GET |
/demographics |
Retrieves a list of all user’s demographics you have access to |
|
GET |
/demographics/{id} |
Retrieves information of a specific user’s demographics |
Enrollments
|
GET |
/enrollments |
Gets a list of student’s enrollments you have access to |
|
GET |
/enrollments/{id} |
Gets only a specific student’s enrollments information |
|
GET |
/schools/{id}/classes/{id}/enrollments |
Retrieves enrollments for classes in schools |
|
GET |
/schools/{id}/enrollments |
Retrieves enrollments for schools |
Teachers
|
GET |
/teachers |
Gets a list of teachers you have access to |
|
GET |
/teachers/{id} |
Gets only a specific teachers information |
|
GET |
/schools/{id}/classes/{id}/teachers |
Retrieves teachers for classes in schools |
|
GET |
/schools/{id}/teachers |
Retrieves teachers for schools |
|
GET |
/classes/{id}/teachers |
Retrieves teachers for classes |
Students
|
GET |
/students |
Gets a list of students you have access to |
|
GET |
/students/{id} |
Gets only a specific students information |
|
GET |
/schools/{id}/classes/{id}/students |
Retrieves students for classes in schools |
|
GET |
/schools/{id}/students |
Retrieves students for schools |
|
GET |
/classes/{id}/students |
Retrieves students for classes |
GrandingPeriods
|
GET |
/gradingPeriods |
Gets a list of grading periods you have access to |
|
GET |
/gradingPeriods/{id} |
Gets only a specific grading period |
Categories
|
GET |
/categories |
Gets a list of categories you have access to |
|
GET |
/categories/{id} |
Gets only a specific category information |
|
PUT |
/categories/{id} |
Creates or updates a category |
|
DELETE |
/categories/{id} |
Deletes a specific category |
Results
|
GET |
/results |
Gets a list of results you have access to |
|
GET |
/classes/{id}/results |
Gets results for a specific class |
|
GET |
/classes/{classId}/lineItems/{id}/results |
Gets results for line items in classes |
|
GET |
/classes/{classId}/students/{id}/results |
Gets results for students in classes |
|
GET |
/results/{id} |
Gets a specific result |
| PUT | /results/{id} | Creates or updates a result |
| DELETE | /results/{id} | Deletes a specific result |
LineItems
|
GET |
/lineItems |
Gets a list of line items you have access to |
|
GET |
/classes/{id}/lineItems |
Get line items for a specific class |
|
GET |
/lineItems/{id} |
Gets a specific line item |
|
PUT |
/lineItems/{id} |
Creates or updates a line item |
|
DELETE |
/lineItems/{id} |
Delete a specific result |
Note: If Grade Sync is disabled, the gragebook attributes (GrandingPeriods, Categories, Results, LineItems) are unavailable
Typical request parameters
|
Parameter |
Mode |
Type |
Description |
|
access_token |
Required |
String |
The access token obtained during authorization |
|
id |
Required |
GUID |
An ID of a requested entity |
|
limit |
Optional |
Number |
Max records returned (default 100). The maximum value for limit is 500 |
|
offset |
Optional |
Number |
The index of the first record to return (zero indexed) |
For example:
- Return the first 10 resources in a collection of students:
GET https://hostname/learningdata/v1/students?limit=10 - Return the second 10 resources in a collection of students:
GET https://imsglobal.org/learningdata/v1/students?limit=10&offset=10
Structure of JSON response from API
With a single data entity:
{
"entityname":{
"sourcedId": "000bc9f5-8496-4b40-92d5-97d74f9b21f8",
"attribute1": "value of attribute 1",
"attribute2": "value of attribute 2",
"attribute3": "value of attribute 3"
"entityreferences":[
{
"href": "https://<hostname>/</learningdata/v1 or /ims/oneroster/v1p1>/<related entityname>/<related entity sourcedId>",
"sourcedId": "<related entity sourcedId>",
"type": "<related entity type>"
},
…
{
"href": "https://<hostname>/</learningdata/v1 or /ims/oneroster/v1p1>/<related entityname>/<related entity sourcedId>",
"sourcedId": "<related entity sourcedId>",
"type": "<related entity type>"
}
]
}
}
With multiple data entities:
{
"entityname": [
{
"sourcedId": "000bc9f5-8496-4b40-92d5-97d74f9b21f8",
"attribute1": "value of attribute 1",
"attribute2": "value of attribute 2",
"attribute3": "value of attribute 3"
"entityreferences":[
{
"href": "https://<hostname>/</learningdata/v1 or /ims/oneroster/v1p1>/<related entityname>/<related entity sourcedId>",
"sourcedId": "<related entity sourcedId>",
"type": "<related entity type>"
},
…
{
"href": "https://<hostname>/</learningdata/v1 or /ims/oneroster/v1p1>/<related entityname>/<related entity sourcedId>",
"sourcedId": "<related entity sourcedId>",
"type": "<related entity type>"
}
]
},
….
{
"sourcedId": "000bc9f5-8496-4b40-92d5-97d74f9b21f8",
"attribute1": "value of attribute 1",
"attribute2": "value of attribute 2",
"attribute3": "value of attribute 3"
"entityreferences":[
{
"href": "https://<hostname>/</learningdata/v1 or /ims/oneroster/v1p1>/<related entityname>/<related entity sourcedId>",
"sourcedId": "<related entity sourcedId>",
"type": "<related entity type>"
},
…
{
"href": "https://<hostname>/</learningdata/v1 or /ims/oneroster/v1p1>/<related entityname>/<related entity sourcedId>",
"sourcedId": "<related entity sourcedId>",
"type": "<related entity type>"
}
]
}
]
Extensions
Metadata (Yes/No) - whether extension added as metadata
Users
|
Metadata |
Attribute |
Description |
|
Yes |
gg4l.home_phone |
User’s home phone number |
|
Yes |
gg4l.work_phone |
User’s work phone number |
|
Yes |
gg4l.preferred_contact_method |
Supported values: "email", "mobile_phone", "home_phone", "work_phone" |
|
Yes |
primaryGrade |
Returns the grade that come from SIS (for students). |
|
Yes |
gg4l.primarySchool |
Returns the primary schools for students and teachers |
Demographics
|
Metadata |
Attribute |
Description |
|
Yes |
gg4l.preferred_language |
User’s preferred language (as in SIS/LMS) |