This guide provides an overview of the primary components that make up the Google Classroom API. The Google Classroom API consists of resources and services. Resources represent entities in Google Classroom, like a course or assignment, and services retrieve and manage these resources. Some of these entities have additional properties specific to the API in addition to what exists in Classroom. The primary entity types are:
Entity | Representation in Classroom |
---|---|
Courses | A class, like "M. Smith's 4th period math". |
Aliases | An alternative ID for a course. |
Invitations | A means to add users to a class. |
Students | A student in a class. |
Teachers | A teacher in a class. |
User profiles | A user more generically, outside the context of student or teacher. |
CourseWork | An assignment in a class. |
StudentSubmissions | A students work for a given assignment, like answers or worksheets. |
CourseWorkMaterials | Materials for students in a class. |
Announcements | An announcement to students in a class. |
AddOnAttachment | Content or an activity on an assignment or material that is typically displayed as an embedded iframe. |
Topics | A visual grouping of assignments and materials in a class. |
Registrations | An instruction to send notifications to your app for changes in data, like a class roster. |
Most resources have service methods for standard operations like reading, updating, and deleting instances of the resource. Some resources also have custom methods for other operations, such as modifying the list of students assigned a particular assignment.
For detailed information on the API resources and methods, refer to the Classroom API reference.
Resource relationships overview
- The Course is the foundational data object in Google Classroom.
- Aliases are used as alternative identifiers for
Courses
. - Invitations are used to invite User profiles to become Teachers
or Students in a
Course
, but users can also be added directly by Google Workspace for Education domain administrators. - Teachers create Stream items and share them with students in their
courses. The possible stream item types are Coursework,
CourseWorkMaterials, and
Announcements. The
CourseWork
andCourseWorkMaterials
can be visually organized into Topics, and can contain AddOnAttachments. Students submit StudentSubmissions for theirCourseWork
. - Developers can create Registrations to get notifications when some of this data changes.
Google Classroom is available to domains that subscribe to Google Workspace for Education. A domain in the Classroom context typically represents a school district. You can create a Google Workspace for Education test domain for the purposes of development, which gives you control of a production instance of Classroom without affecting real users.
Courses and aliases
Courses
represent a class, such as "M. Smith's 4th period math", and its
assigned teachers, student roster, and metadata. Each course is identified by a
unique ID assigned by the server. The Course
resource specifically
encapsulates all of the metadata about the course, such as the name,
description, location, and time. Course rosters are managed through the
Student, Teacher, and Invitation
resources and their methods.
Aliases
are alternate identifiers for a class that may be associated with a
course and used in place of the unique ID. Each alias exists in a namespace that
restricts who can create and view it. Two namespaces are supported:
- Domain: The domain namespace is useful for creating aliases that all users need access to, but that are not specific to any one program. For example, alternate listings for a course, such as MATH 127 and COMSCI 127, should be created in the domain namespace. Aliases in the domain namespace may only be created by domain administrators but are visible to all users in a domain.
- Developer project: The developer project namespace is useful for managing aliases specific to an application. For example, an application that uses alternate identifiers for courses can create aliases to map its identifier to Classroom courses. Aliases created in this namespace are tied to a specific Google API Console. Any user of an application can create and view aliases in the namespace for that application's developer project.
For more information about managing course metadata and aliases, see Manage Courses.
Course rosters and users
Students
and Teachers
are specific mappings between a user profile and a
course, representing that user's role in the course. Designations of student and
teacher are not global: a user can be assigned as a teacher for one course and a
student in another. The designation "student" or "teacher" represents a set of
permissions for a particular user in a particular course.
- Students
A
Student
resource represents a user who is enrolled as a student in a specific course.Students are permitted to view the course details and teachers for that course.
- Teachers
A
Teacher
resource represents a user who teaches a specific course.Teachers are permitted to view and change the course details, view teachers and students, and manage additional teachers and students.
Invitations
and their associated methods provide a convenient way of adding
students and teachers to courses. Creating invitations allows users to choose
whether or not to join a course, rather than you directly adding them through
the teacher and student resources.
UserProfiles
represent a mapping to a user's domain profile as identified by
the unique ID or email address of the user returned by the
Directory API. The current user may also refer to their own
ID using the "me"
shorthand.
The UserProfiles
service can also be used to manage and invite Guardians
,
which are a mapping between a student and guardian. Guardians in
Classroom have access to some student information, like their
assignments.
For more information on managing rosters, see Manage Teachers and Students.
Coursework and student submissions
A CourseWork
item represents a single task assigned to a group of students
in a course. It contains details such as the description, due date, and
materials as well as metadata such as creation time. Materials include a title,
thumbnail, and URL, as well as an identifier that can be used with the
appropriate APIs (i.e. Drive, YouTube).
CourseWork
items describe one of the following types of tasks:
- An assignment that students complete by submitting worksheets or other attachments.
- A short answer question or multiple choice question.
Student work for a CourseWork
item is represented by a StudentSubmission
.
It consists of a response and additional metadata such as a state and assigned
grade.
The contents of a StudentSubmission
depend on the type of the corresponding
CourseWork
item:
- The worksheets and attachments submitted for an assignment, including their title, thumbnail, and URL, as well as identifiers that can be used with the appropriate APIs such as Drive or YouTube.
- The response to a short answer question or multiple choice question.
For more information about managing coursework and student submissions, see Manage Classwork.
Coursework materials and announcements
Similar to CourseWork
, CourseWorkMaterials
represent content assigned to a
group of students in a course, with details like a title and description, along
with materials. However, unlike CourseWork
, CourseWorkMaterials
don't
require students to submit any artifacts. As such, there is no due date, and
StudentSubmissions
don't exist for CourseWorkMaterials
. Teachers might use
CourseWorkMaterials
to post suggested readings, a syllabus, or classroom
rules, for example.
Announcements
also represent content shared with a group of students, but
don't have details like a title, and can't be organized by Topics
like
CourseWork
or CourseWorkMaterials
. Teachers might use these to announce
reminders or notices to the class.
Topics
Topics
are used to visually organize CourseWork
and CourseWorkMaterials
within a class. These might be used to group assignments into "optional" and
"required", or "unit 1" and "unit 2", for example.
Classroom add-ons
An add-on is a developer-served UI and backend typically displayed in an
iframe. Add-ons appear as attachments on a stream item. The stream item
can be any Announcements
, CourseWork
, or CourseWorkMaterials
. Add-on
attachments are represented by an AddOnAttachment
.
Add-on attachments can be an activity or content.
- Activity attachments require a student to complete and turn-in an individual submission. Examples include quizzes, drawings, or games. An activity submission can optionally be graded.
- Content attachments don't require a student submission. The student doesn't need to turn-in the attachment and it's not graded. Examples include photos, articles and videos.
See the add-ons development guides for more information.
Registrations
Applications can subscribe for notifications when certain data changes in
Google Classroom. For example, when the roster of a course is updated.
Registrations
represent an instruction to send these notifications to your
application.
See the push notifications guide to learn more.