Contents

Data API schema

OAuth 2 authorization - “Client credentials” grant

API Overview

Districts:

Teachers:

Students:

Sections:

Schools:

District_admins:

School_admins:

Events:

Contacts:

Supported event types

Typical request parameters

Structure of JSON response from API


 

Data API schema

Data API schema reflected in SSO Passport API data schema document

 

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 API is /datahub/services

 

Districts:

                          

GET

/v1/districts

Retrieves a list of districts you have access to

GET

/v1/districts/{id}

Retrieves information of a specific district

GET

/v1/districts/{id}/schools

Retrieves a list of schools you have access to for a specific district

GET

/v1/districts/{id}/teachers

Retrieves a list of teachers you have access to for a specific district

GET

/v1/districts/{id}/students

Retrieves a list of students you have access to for a specific district

GET

/v1/districts/{id}/sections

Retrieves a list of sections you have access to for a specific district

GET

/v1/districts/{id}/admins

Retrieves all the users with admin access to a district

GET

/v1/districts/{id}/status

Retrieves the status of a district

GET

/v1/districts/{id}/events

Retrieves all events for all resources belonging to this district

 

Teachers:

                          

GET

/v1/teachers

Gets a list of teachers you have access to

GET

/v1/teachers/{id}

Get only a specific teacher's information

GET

/v1/teachers/{id}/events

Retrieves events for teachers

GET

/v1/teachers/{id}/sections

Retrieves a list of all sections for a teacher

GET

/v1/teachers/{id}/school

Retrieves information about the school for a teacher

GET

/v1/teachers/{id}/district

Retrieves district information for a teacher

GET

/v1/teachers/{id}/students

Retrieves all students that a teacher has in their sections

GET

/v1/teachers/{id}/grade_levels

Retrieves a list of all grade levels taught by a specific teacher

 

Students:

                          

GET

/v1/students

Gets a list of students you have access to

GET

/v1/students/{id}

Get only a specific student's information

GET

/v1/students/{id}/events

Retrieves events for students

GET

/v1/students/{id}/sections

Retrieves a list of all sections for a student

GET

/v1/students/{id}/school

Retrieves information about the school for a student

GET

/v1/students/{id}/district

Retrieves district information for a student

GET

/v1/students/{id}/teachers

Retrieves all teachers for a student

GET

/v1/students/{id}/contacts

Retrieves all contacts for a student

 

Sections:

                          

GET

/v1/sections

Gets a list of sections you have access to

GET

/v1/sections/{id}

Get only a specific section's information

GET

/v1/sections/{id}/events

Retrieves events for sections

GET

/v1/sections/{id}/school

Retrieves information about the school for a section

GET

/v1/sections/{id}/district

Retrieves district information for a section

GET

/v1/sections/{id}/students

Retrieves a list of all the section's students

GET

/v1/sections/{id}/teachers

Retrieves a list of all the section's teachers

GET

/v1/sections/{id}/teacher

Retrieves information about the primary teacher of a section

 

Schools:

                          

GET

/v1/schools

Gets a list of schools you have access to

GET

/v1/schools/{id}

Get only a specific school's information

GET

/v1/schools/{id}/events

Retrieves events for schools

GET

/v1/schools/{id}/teachers

Retrieves a list of all teachers for a specific school

GET

/v1/schools/{id}/students

Retrieves a list of all students for a specific school

GET

/v1/schools/{id}/sections

Retrieves a list of all sections for a specific school

GET

/v1/schools/{id}/district

Retrieves district information for a school

 

District_admins:

                          

GET

/v1/district_admins

Retrieves all users with admin access to a district

GET

/v1/district_admins/{id}

Retrieves a district admin

 

School_admins:

                          

GET

/v1/school_admins

Gets a list of school admins you have access to

GET

/v1/school_admins/{id}

Get only a specific school admin's information

GET

/v1/school_admins/{id}/schools

Retrieves all schools for a school admin

 

Events:

                          

GET

/v1/events

Gets a list of all events that have occurred within data you have access to see

GET

/v1/events/{id}

Retrieves specific event information

 

Contacts:

                          

GET

/v1/contacts

Gets a list of student contacts you have access to

GET

/v1/contacts/{id}

Get only a specific student contact's information

GET

/v1/contacts/{id}/student

Retrieves the student for a contact

GET

/v1/contacts/{id}/district

Retrieves the district for a contact

 

Supported event types

                          

Created

Updated

Deleted

schools.created

students.created

studentcontacts.created

teachers.created

sections.created

schooladmins.created

schools.updated

students.updated

studentcontacts.updated

teachers.updated

sections.updated

schooladmins.updated

schooladmins.deleted

sections.deleted

teachers.deleted

studentcontacts.deleted

students.deleted

schools.deleted

 

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)

created_since

Optional

ISO 8601

Applies to /events API. Example: created_since=2016-07-26T16:35:04.084Z

page

Optional

Number

Which page of results to return (default 1)

search_token

Optional

String

URI that allows to get the next page of the paginated response. It is the value of “uri” element that follows "rel": "NEXT" in “links” section of JSON response (see example in the next section)

 

Structure of JSON response from API

… with a single data entity:

{
 "data": {

    "id": "000bc9f5-8496-4b40-92d5-97d74f9b21f8",
    "attribute1": "value of attribute 1",

    "attribute2": "value of attribute 2",
    "attribute3": "value of attribute 3"
 },
 "links": [
   {
     "rel": "self",
     "uri": "/v1/entityname/000bc9f5-8490-4b4c-92d5-97d74f9b21f8"
   },
   {
     "rel": "related-entity1",
     "uri": "/v1/entityname/000bc9f5-8490-4b4c-92d5-97d74f9b21f8/related-entity1"
   },
   {
     "rel": "related-entity2",
     "uri": "/v1/districts/000bc9f5-8496-4b40-92d5-97d74f9b21f8/related-entity2"
   }

 ]
}

 

… with multiple data entities:

{
 "data": [
   {
     "data": {
       "id": "000bc9f5-8496-4b40-92d5-97d74f9b21f8",
       "attribute1": "value of attribute 1",

       "attribute2": "value of attribute 2",
       "attribute3": "value of attribute 3"
     },
     "uri": "/v1/entityname/000bc9f5-8496-4b4c-92d5-97d74f9b21f8"
   },
   {
     "data": {
       "id": "111ac1f5-8496-4b40-92d5-97d74f9b21f9",
       "attribute1": "value of attribute 1",

       "attribute2": "value of attribute 2",
       "attribute3": "value of attribute 3"
     },
     "uri": "/v1/entityname/111ac1f5-8490-4b4c-92d5-97d74f9b21f9"
   },

   ...
 ],
 "paging": {
   "current": 1,
   "total": 2,
   "count": 148
 },
 "links": [
   {
     "rel": "NEXT",
     "uri": /v1/entityname?search_token=2.2.148.FORWARD.111ac1f5-8490-4b4c-92d5-97d74f9b21f9"
   },
   {
     "rel": "SELF",
     "uri": "/v1/entityname"
   }
 ]
}