Events API v1

This article provides an overview of the Events API schema.

In this article

Revisions

1. OAuth 2 authorization - “Client credentials” grant

2. Events API endpoints

3. Supported types (“eventType”) of Event data

4. Pagination

5. Supported request parameters

6. Extensions to One Roster data model

7. Format of API responses

7.1 JSON format of a generic response

7.2 JSON format of a Created type of Event data

7.3 JSON format of a Updated type of Event data

7.4 JSON format of a Deleted type of Event data

7.5 JSON format of an Enrollment Event data

Revisions

Document version

Change Description

Effective Date

1.2

Added note that "before" and "after" parameters are uses only for "/events" endpoint for #5.

May 15, 2024

1.1

"User.Enrolled" and "User.Unenrolled" eventType values are replaced with Enrollment.Created & Enrollment.Deleted respectively

Apr 30, 2020

1.0

Initial release

Jan 15, 2020

1. 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:

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 type, which is always 'bearer.’
expires_in Integer Expiration time in seconds
scope String List of scopes that define data access level

 

 

 

2. Events API endpoints

The base path for Events API v1.1 is /datahub/services/ims/oneroster/v1p1

GET

/events

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

GET

/orgs/{id}/events

Retrieves events for an organization

GET

/schools/{id}/events

Retrieves events for a school data object

GET

/academicSessions/{id}/events

Retrieves events for an academic session

GET

/classes/{id}/events

Retrieves events for a class

GET

/courses/{id}/events

Retrieves events for a course

GET

/teachers/{id}/events

Retrieves events for a teacher

GET

/students/{id}/events

Retrieves events for a student

GET

/terms/{id}/events

Retrieves events for a term

GET

/users/{id}/events

Retrieves events for a user

GET

/demographics/{id}/events

Retrieves events for demographics

3. Supported types (“eventType”) of Event data 

Created

Updated

Deleted

AcademicSession.Created

Contact.Created

Course.Created

Class.Created

Demographic.Created

District.Created

Enrollment.Created

School.Created

Student.Created

Teacher.Created

AcademicSession.Updated

Contact.Updated

Course.Updated

Class.Updated

Demographic.Updated

District.Updated

Enrollment.Updated

School.Updated

Student.Updated

Teacher.Updated

AcademicSession.Deleted

Contact.Deleted

Course.Deleted

Class.Deleted

Demographic.Deleted

District.Deleted

Enrollment.Deleted

Student.Deleted

School.Deleted

Teacher.Deleted

4. Pagination

Every response has a “Link” HTTP header element that contains URLs to retrieve the next and the previous page of data.  The format of that data: {uri_prev}; rel=“prev”, {uri_next}; rel=“next”

Value of “rel”

Description

self

Corresponds to a URI that was sent for this request

prev

Corresponds to a URI to retrieve the previous “page” of data

next

Corresponds to a URI to retrieve the next “page” of data

5. Supported request parameters

Parameter

Mode

Type

Description

access_token

Required

String

The access token obtained during authorization

after

Optional

Number

Only for "/events" endpoint.

{miliseconds_from_epoch} Example=1548944937314

before

Optional

Number

Only for "/events" endpoint.

{miliseconds_from_epoch} Example=1548944937314

since

Optional

ISO 8601

Example: since=2020-01-20T16:35:04.084Z

Support for “since” query parameter is being deprecated. GG4L encourages use of the “after” parameter instead.

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)

GG4L encourages use of “Link” HTTP header values for navigation through a paginated data (see “Pagination” section).

For example:

GET https://hostname/students?limit=10 - return the first 10 resources in a collection of students.

GET https://hostname/students?limit=10&offset=10 - return the second 10 resources in a collection of students.

6. Extensions to One Roster dataUsers model

Metadata (Yes/No) - whether extension is a part of One Roster metadata.

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 primary grade 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)

7. Format of API responses

7.1. JSON format of a generic response

{
  "events": [
    {
      "sourcedId": "string",
      "timestamp": "string",
      "eventType": "AcademicSession.Created",
      "object": {
        "dateLastModified": "string",
        "sourcedId": "string",
        "status": "string"
      },
      "changes": {
        "dateLastModified": "string",
        "sourcedId": "string",
        "status": "string"
      }
    }
    … 

    {JSON_of_the_last_event_object}
  ]
}

7.2. JSON format of a Created type of Event data

{
  "sourcedId": "17764f9c-7148-4310-b9ba-62f2365d1b5d",
  "eventType": "Teacher.Created",
  "timestamp": "2020-01-09T13:56:06.909Z",
  "object": {
    "sourcedId": "68dffad5-a464-4d47-a00f-b4dbd92ba07d",
    "status": "active",
    "dateLastModified": "2020-01-09T13:56:06.909Z",
    "metadata": {
      "gg4l.primary_school": "5dfcf075-c905-401e-9119-7c5331410dec",
      "gg4l.preferred_contact_method": "email"
    },
    "username": "74115385",
    "userIds": [
      {
        "type": "ORid",
        "identifier": "98124"
      },
      {
        "type": "sftp_id",
        "identifier": "staff_01"
      },
      {
        "type": "statID",
        "identifier": "staff_01"
      }
    ],
    "enabledUser": "false",
    "givenName": "Nette",
    "familyName": "Notkent",
    "middleName": "Nett",
    "role": "teacher",
    "identifier": "032134154",
    "email": "nette.notken@tesmail.com",
    "sms": "0212234654",
    "phone": "0212234654",
    "orgs": [
      {
        "href": "https://hostname/orgs/5dfcf075-c905-401e-9119-7c5331410dec",
        "type": "org",
        "sourcedId": "5dfcf075-c905-401e-9119-7c5331410dec"
      },
      {
        "href": "https://hostname/orgs/71eeebef-54a9-456a-9a7a-d71af5eaff97",
        "type": "org",
        "sourcedId": "71eeebef-54a9-456a-9a7a-d71af5eaff97"
      }
    ],
    "password": "98654"
  }
}

7.3. JSON format of a Updated type of Event data

Updated type of Event data object contains changes JSON section

{
  "sourcedId": "c949f252-13e2-4507-a9de-cab901d0065e",
  "eventType": "Student.Updated",
  "timestamp": "2020-01-13T12:38:13.023Z",
  "object": {
    "sourcedId": "885de493-5ae8-4688-858d-db66b5b277d1",
    "status": "active",
    "dateLastModified": "2020-01-13T12:38:13.023Z",
    "metadata": {
      "gg4l.primaryGrade": "06",
      "metadata.pnpfileurl": "facebook.com",
      "gg4l.primary_school": "5dfcf075-c905-401e-9119-7c5331410dec",
      "gg4l.preferred_contact_method": "email"
    },
    "username": "54021",
    "userIds": [
      {
        "type": "ORid",
        "identifier": "98124"
      },
      {
        "type": "LDAPid",
        "identifier": "14785236"
      },
      {
        "type": "sftp_id",
        "identifier": "student_04"
      },
      {
        "type": "statID",
        "identifier": "student_04"
      }
    ],
    "enabledUser": "false",
    "givenName": "Clark45",
    "familyName": "Kent43",
    "middleName": "F4",
    "role": "student",
    "identifier": "11242385",
    "email": "claek.kent44@tesmail.com",
    "sms": "12345678975",
    "phone": "8521747994564",
    "agents": [
      {
        "href": "https://hostname/datahub/services/ims/oneroster/v1p1/users/51b0ef66-8f58-4e12-9c6c-9dd344962441",
        "type": "user",
        "sourcedId": "51b0ef66-8f58-4e12-9c6c-9dd344962441"
      }
    ],
    "orgs": [
      {
        "href": "https://hostname/datahub/services/ims/oneroster/v1p1/orgs/5dfcf075-c905-401e-9119-7c5331410dec",
        "type": "org",
        "sourcedId": "5dfcf075-c905-401e-9119-7c5331410dec"
      },
      {
        "href": "https://hostname/datahub/services/ims/oneroster/v1p1/orgs/ca8614fa-6dd2-465f-b817-ad78c9194755",
        "type": "org",
        "sourcedId": "ca8614fa-6dd2-465f-b817-ad78c9194755"
      }
    ],
    "grades": [
      "06"
    ],
    "password": "24547687"
  },
  "changes": {
    "username": "000054021",
    "givenName": "Clark4",
    "familyName": "Kent4"
  }
}

7.4. JSON format of a Deleted type of Event data

{
  "sourcedId": "4262f51a-9765-468b-b991-d0fe15dfc3cd",
  "eventType": "Course.Deleted",
  "timestamp": "2020-01-13T16:07:03.577Z",
  "object": {
    "sourcedId": "7dfdeba7-d75a-4361-b5d1-19184a40d6d2",
    "status": "active",
    "dateLastModified": "2020-01-09T13:56:06.922Z",
    "metadata": {
      "metadata.duration": "two weeks"
    },
    "title": "WORLD MATH",
    "schoolYear": {
      "href": "https://hostname/datahub/services/ims/oneroster/v1p1/academicSessions/ec08a5ae-8b32-47a6-b48a-af3000e2475c",
      "type": "academicSession",
      "sourcedId": "ec08a5ae-8b32-47a6-b48a-af3000e2475c"
    },
    "courseCode": "01012",
    "grades": [
      "04",
      "03"
    ],
    "subjects": [
      "Technology"
    ],
    "org": {
      "href": "https://hostname/datahub/services/ims/oneroster/v1p1/orgs/8c9693ea-c15c-45b4-905c-d44d0e5bb53f",
      "type": "org",
      "sourcedId": "8c9693ea-c15c-45b4-905c-d44d0e5bb53f"
    },
    "subjectCodes": [
      "03210"
    ]
  }
}

7.5. JSON format of an Enrollment Event data

This type of Event gets generated when:

  • a user gets enrolled/unenrolled into/from a class
  • there are changes (like start/end date) to user’s enrollment details
  • a class, that a user is enrolled into, gets created or deleted
{
  "sourcedId": "1fcb34db-9d46-4595-a17a-6b86ee56ed4b",
  "eventType": "User.Enrolled",
  "timestamp": "2020-01-13T15:31:19.380Z",
  "object": {
    "sourcedId": "56c70491-8962-4bea-8f71-ade2c4f98c79",
    "status": "active",
    "dateLastModified": "2020-01-13T15:31:19.380Z",
    "role": "teacher",
    "primary": "false",
    "user": {
      "href": "https://hostname/datahub/services/ims/oneroster/v1p1/users/68dffad5-a464-4d47-a00f-b4dbd92ba07d",
      "type": "user",
      "sourcedId": "68dffad5-a464-4d47-a00f-b4dbd92ba07d"
    },
    "class": {
      "href": "https://hostname/datahub/services/ims/oneroster/v1p1/classes/b0d94f63-419c-41fc-affd-ec66ea8f1458",
      "type": "class",
      "sourcedId": "b0d94f63-419c-41fc-affd-ec66ea8f1458"
    },
    "school": {
      "href": "https://hostname/datahub/services/ims/oneroster/v1p1/orgs/5dfcf075-c905-401e-9119-7c5331410dec",
      "type": "org",
      "sourcedId": "5dfcf075-c905-401e-9119-7c5331410dec"
    },
    "beginDate": "2018-06-06",
    "endDate": "2020-12-07"
  }
}