Contents


OAuth 2 authorization - “Client credentials” grant
API Overview
    
Organizations
    
Schools
    
AcademicSessions
    
Terms
    
Courses
    
Classes
    
Users
    
Demographics
    
Enrollments
    
Teachers
    
Students
    Typical request parameters
Structure of JSON response from API


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.0 is /datahub/services/learningdata/v1

 

 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, Categiries, Results and LineItems endpoints are not supported.




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)
 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> "

              }  

        ]

     }
   ]
  }