How requests work

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 & mange 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 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:

1. The id of the resource to modify.
2. 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.

Tip: You might notice update() methods alongside patch() methods. While both modify a resource, they differ in behavior. Update() completely replaces a resource with a new one, while patch() only updates select fields. For example, courses.update() replaces an entire existing Course, while courses.patch() uses the aforementioned fieldMask to modify only specific fields in the Course. For simplicity, the Google Classroom API almost exclusively uses patch(), and it's recommended that you use that method generally.

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.