Push notifications in the Classroom API

You can use the methods on the Registrations collection to receive notifications when data changes in Classroom.

This article provides a conceptual overview along with simple instructions on how to start receiving push notifications.

Overview of Classroom push notifications

The Classroom API push notifications feature allows applications using the Classroom API to subscribe for notifications when data changes in Classroom. Notifications are delivered to a Cloud Pub/Sub topic, usually within a few minutes of the change.

To receive push notifications, you need to set up a Cloud Pub/Sub topic and provide that topic's name when you create a registration for the appropriate feed of notifications.

Below are definitions of key concepts used in this documentation:

  • A destination is a place where notifications are sent.
  • A feed is a type of notifications that a third party application can subscribe to. For example, "roster changes for course 1234".
  • A registration is an instruction to the Classroom API to deliver notifications from a particular feed to a destination.

Once you create a registration for a feed, that registration's Cloud Pub/Sub topic receives notifications from that feed until it expires. Your registration lasts a week, but you can extend it at any point before it expires by making an identical request to registrations.create().

Your Cloud Pub/Sub topic only receives notifications about resources that you can view with the credentials you supply when creating a registration. For example, if the user revokes permission from your application or is removed as a teacher, notifications are longer delivered.

Types of feeds

The Classroom API currently offers three types of feed:

  • Each domain has a roster changes for domain feed, which exposes notifications when students and teachers join and leave courses in that domain.
  • Each course has a roster changes for course feed, which exposes notifications when students and teachers join and leave courses in that course.
  • Each course has a course work changes for course feed, which exposes notifications when any course work or student submission objects are created or modified in that course.

Setting up a Cloud Pub/Sub topic

Notifications are delivered to Cloud Pub/Sub topics. From Cloud Pub/Sub, you can receive notifications on a web hook, or by polling a subscription endpoint.

To set up a Cloud Pub/Sub topic, you need to do the following:

  1. Make sure you fulfill the Cloud Pub/Sub Prerequisites.
  2. Set up a Cloud Pub/Sub client.
  3. Review the Cloud Pub/Sub pricing, and enable billing for your Developer Console project.
  4. Create a Cloud Pub/Sub topic in the Developer Console (easiest), via the command line tool (for simple programmatic use) or using the Cloud Pub/Sub API. Note that Cloud Pub/Sub only allows a limited number of topics, so using one topic to receive all your notifications ensures you do not hit scaling issues if your application becomes popular.

  5. Create a Subscription in Cloud Pub/Sub, to tell Cloud Pub/Sub how to deliver your notifications.

  6. Finally, before registering for Push Notifications, you need to grant the Push Notifications service account (classroom-notifications@system.gserviceaccount.com) permission to publish to your topic.

NOTE: If you grant the Push Notifications service account permission to publish to your Cloud Pub/Sub topic, users who can make requests from your Developer Console project will be able to determine that it exists, and register for notifications to it. Many applications store OAuth Client IDs on the client side, so end-users might be able to make requests from your Developer Console project. If this applies to you, and you are concerned about end-users sending unwanted notifications to your Cloud Pub/Sub topic or knowing the names of Cloud Pub/Sub topics that you use for push notifications, you should consider registering for push notifications from a different Developer Console project.

Register your application for notifications

Once you have a topic that the Classroom API push notifications service account can publish to, you can register for notifications, using the registrations.create() method. The registrations.create() method validates that the provided Cloud Pub/Sub topic can be reached by the push notifications service account. The method fails if the push notifications service account cannot reach the topic; for example, if the topic does not exist or you have not granted it publish permission on that topic.

Authorization

Like all calls to the Classroom API, calls to registrations.create() must be authorized with an authorization token. This authentication token must include the Push Notifications scope (https://www.googleapis.com/auth/classroom.push-notifications) and whatever scopes are required to view the data about which notifications are being sent.

  • For roster change feeds, this means the Rosters scope or (ideally) its read-only variant (https://www.googleapis.com/auth/classroom.rosters.readonly or https://www.googleapis.com/auth/classroom.rosters).
  • For course work change feeds, this means the "students" versions of the course work scope or (ideally) its read-only variant (https://www.googleapis.com/auth/classroom.coursework.students.readonly or https://www.googleapis.com/auth/classroom.coursework.students).

For notifications to be delivered, the application must retain an OAuth grant from the authorized user with the required scopes. If the user disconnects the application, notifications cease. Note that currently, domain-wide delegation of authority is not supported for this purpose. If you attempt to register for notifications using only domain-wide delegated authority, you will receive a @MissingGrant error.

Receiving notifications

Notifications are encoded with JSON, and contain:

  • The name of the collection containing the resource that changed. For notifications about roster changes, this is either courses.students or courses.teachers. For course work changes, this is either courses.courseWork or courses.courseWork.studentSubmissions.
  • Identifiers for the resource that changed, in a map. This map is designed to match the arguments to the get method of the appropriate resource. For notifications about roster changes, the courseId and userId fields will be populated, and can be sent unmodified to courses.students.get() or courses.teachers.get(). Similarly, changes to the courses.courseWork collection will have courseId and id fields that can be sent unmodified to courses.courseWork.get() and changes to the courses.courseWork.studentSubmissions collection will have courseId, courseWorkId, and id fields that can be sent unmodified to courses.courseWork.studentSubmissions.get().

The following code snippet demonstrates a sample notification:

{
  "collection": "courses.students",
  "eventType": "CREATED",
  "resourceId": {
    "courseId": "12345",
    "userId": "45678"
  }
}

Notifications also have a registrationId message attribute, containing the identifier for the registration that caused the notification, which can be used with registrations.delete() to unregister from notifications.