This page describes a high-level overview of how requests work in the Google Classroom API. The goal is to aid readers who aren't already familiar with resource-oriented design or Google Workspace APIs.
For specific code samples, see the corresponding API guides, for example Create & manage courses or Create & manage coursework.
Resource-oriented design
As mentioned in API structure, the Classroom API follows resource-oriented design patterns. Most resources have methods for standard operations like creating, reading, updating, and deleting instances of the resource.
For example, it's possible to create(), patch(), get(), list(),
and delete() a Classroom Course using the API.
Create
To create a new resource, like a Course, call the create() method for the
corresponding resource.
Create() calls always require the initial, critical details of the
corresponding resource as input. For example, to create a Course, call the
create() method on the Course resource and specify the name and
description in the request, along with optional information like the room.
For subresources (sometimes called child resources), identifiers for the parent
resource are also required. For example, when creating a CourseWork within a
Course, the Course id is needed to establish in which Course the
CourseWork belongs.
Create() methods return an instance of the newly created resource in the API
call response. The returned resource typically has any additional,
server-generated fields, such as the resource id or creationTime.
Patch
To modify existing resources, call the patch() method (which is sometimes
called update()) on the corresponding resource. The patch() method is almost
identical to create(), with two key differences; when calling the patch()
method you must specify:
- The
idof the resource to modify. - A list of fields, called an
updateMask, to determine which fields on the resource to update. This is optional in cases where there is a default set of fields or the fields are inferred.
Patch() methods return the full instance of the updated resource in the API
call response, with all changes completed.
Get and list
There are two methods for retrieving resources: get() and list().
The get() method retrieves a specific resource by some identifier. For
example, fetching a Course based on id or alias. The get() call
returns the full resource directly.
The list() method retrieves multiple resources of the same type in a single
request, without the need for the individual resource identifiers. Often the
list() operation gets all the subresources of some parent resource, for
example, retrieving all the CourseWork within a Course. This is useful for
minimizing requests, compared to making multiple get() calls, and particularly
valuable when you don't know the id of the resources you want.
Generally, list() methods have some maximum amount of resources that can be
returned in a single call, and lower limits can be configured by including a
pageSize value with the call. In cases where there are more resources than the
limit, the list() method supports pagination; each "page" of results that is
returned provides a pageToken, which can be included in a subsequent list()
call to fetch the next batch of resources.
Delete
The delete() method accepts a resource identifier, like id, and deletes the
corresponding resource. If the delete() is successful, an empty response is
returned.
Other operations
Not all operations possible with the Classroom API can be achieved
with the aforementioned standard operations, for example, modifying the
assignees of a CourseWork resource. In these cases, custom methods are
available, like the modifyAssignees method. The behavior of these methods
are bespoke and you should consult the documentation for them individually.