Document Version	Change Description	Effective Date
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 must contain WWW BASIC authorization with client_id and client secret key in request header: ‘Authorization’: ‘Basic {data}’

where data = Base64.encode(‘{client_id}:{client secret}’)

POST

datahub/oauth/token

The endpoint to authenticate 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 (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}	Get 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}	Get 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 a 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}	Get 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}	Get 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}	Get 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

GradingPeriods, Categories, Results and LineItems endpoints are not supported yet.

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)