Teachers that leverage both Classroom and third-party tools face the challenge of setting up their courses and rosters across multiple platforms. This might be done manually, either through the use of CSV uploads or entering emails one-by-one. With the Classroom API, however, third-party tools can reduce their teacher's workloads by integrating with the API's most common use case: roster import.
Roster importing allows third-party platforms to retrieve a course's metadata, teachers, and students on a course-by-course basis with either teacher or admin permissions. Teachers can retrieve details of the courses they teach, whereas admins have access to details for all courses across an entire domain. This flexibility allows developers to seamlessly onboard Classroom rosters onto their platform both on an individual-teacher level or across an entire domain by using admin credentials.
Before diving into the technical details of what a roster import integration might look like, let's first review an example workflow:
In the third-party application, a teacher chooses the option to import a Classroom Course.
The third-party application calls the
courses.listmethod through the Classroom API, which will return a response JSON with all the teacher's courses.
From the json response, the third-party application displays the titles of the teacher's courses for them to select one. The application will need to keep track of the course IDs to continue onto the next step.
With the selected course ID, the third-party application calls the
teachers.listmethods and displays all names on its website for teachers to confirm for import.
Using the emails returned in the
teachers.listresponse jsons, the third-party application invites the users to join the newly imported course on their platform.
For each of the methods mentioned in the workflow, you can use the API Explorer to see exactly how each method behaves. We also recommend the following pre-reads before finishing this guide:
Before implementing the specifics of your Classroom roster import, you'll need to determine what course and user information you'll need to retrieve via the API. You can see what Course metadata is available in the Reference documentation, but some required or common fields needed can be summarized below:
|id||Required for API requests retrieving student or teachers|
|name||Recommended for ease of use for the user, i.e. displaying on your website|
|ownerId||Required when importing on a domain-wide basis to correctly identify the main teacher of a course|
This course information is retrieved at the
courses.list step of the workflow
above. In this request you can specify certain request parameters. While none
are required for this method, some recommended parameters are:
|courseState||Left unspecified, the API will return courses of all six course states. We recommend specifying
|pageSize||For teachers who are importing their own courses, we recommend specifying a small (less than 10) pageSize to decrease the API call's response time.|
|pageToken||Required if you're using paged requests.|
|teacherId||Recommended since domain admins often teach courses. Left unspecified, the request will return courses for teachers across the entire domain.|
|fields||Recommended to decrease the API call's response time.|
Using the course IDs retrieved earlier, your application can now retrieve the
list of students and co-teachers for that course or courses. This course ID is
the only required query parameter for
you might similarly want to consider specifying the
parameters to decrease the response time of your API calls.
All available fields for the
resources can be found in their respective documentation. The two mostly
commonly used and typically required needed fields are in the
|profile.name||Recommended for ease of use for the user, i.e. displaying on your website|
|profile.emailAddress||Required for applications looking to uniquely identify students|
To retrieve and use any of these course or roster details from Classroom, your application will need to request authorization from users. There are three (3) required scopes to implement this workflow:
- Provides Read-Only access to Google Classroom Courses
- Provides Read-Only access to the rosters of Google Classroom Courses (teachers and students)
- Provides Read access to the email property of teachers and students
Sync Rosters with Pub/Sub Notifications
As the school year progresses, rosters might change as students drop or add courses. Adding Pub/Sub notifications will allow you to keep your third-party application in sync with Classroom rosters. To receive notifications, you set up a Google Cloud Pub/Sub topic and then register the topic with the Classroom API. This registration is a request for Classroom to send data from the given feed to the given topic. This feed will be the event triggers for re-syncing with a teacher's Classroom roster.
Utilizing push notifications will require one additional scope, which does not have to be submitted for verification:
- Allows your app to register for any push notification activity
For more details on how to integrate with Classroom push notifications, see our Manage Push Notifications guide.