Google Classroom add-ons are now generally available to developers! Please see the add-ons documentation for more information.

Access preview APIs

This page describes how you can access Classroom API preview features and specify preview versions.

The three considerations when using preview features when compared to the stable v1 API are:

The calling Google Cloud project must be enrolled in the Google Workspace Developer Preview Program and allow listed by Google.
API features in early access or preview programs aren't exposed in the standard client libraries and might not be accessible by default over HTTP.
At any given time there might be multiple API states, or versions, in preview.

Enable preview features in client libraries

A common option for consuming the Classroom API is with a client library. There are three types of client libraries:

Dynamically generated client libraries
Google-provided static client libraries
Your own custom client library

Using dynamically generated or Google-provided static libraries is the recommended way to use the API. See build client libraries if you need to build your own library. Creating your own library is outside the scope of this guide, but you should review the dynamic libraries section to learn about preview labels and their role in Discovery.

Dynamic libraries

Libraries in languages like Python generate the client library at runtime using a Discovery Document from the Discovery service.

A Discovery Document is a machine-readable specification for describing and consuming REST APIs. It's used to build client libraries, IDE plugins, and other tools that interact with Google APIs. One service might provide multiple discovery documents.

Discovery Documents for the Classroom API service (classroom.googleapis.com) can be found at the following endpoint:

https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY

The important distinction for working with preview APIs is specifying the appropriate label. For Classroom public previews that label is DEVELOPER_PREVIEW.

To generate the Python library and instantiate the Classroom service with preview methods, you can specify the Discovery URL with the appropriate service, credentials, and label:

classroom_service_with_preview_features = googleapiclient.discovery.build(
  serviceName='classroom',
  version='v1',
  credentials=credentials,
  static_discovery=False,
  discoveryServiceUrl='https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key=API_KEY)'

See the individual Google API client library documentation for details on each language.

Static libraries

Client libraries in languages like Java, Node.js, PHP, C#, and Go must be built from source. These libraries are provided for you and have the preview features already incorporated.

For public previews, Classroom client libraries can be found with the other Workspace Developer Preview Program client libraries. For private previews, reach out to your Google contact if you need static libraries generated.

You might need to modify your typical dependencies configuration to use these local libraries rather than importing the standard client libraries, which don't have the preview features.

For example, to use the Go client library, you need to use the replace directive in your go.mod file to require a module from a local directory:

module example.com/app

go 1.21.1

require (
    golang.org/x/oauth2 v0.12.0
    google.golang.org/api v0.139.0 // Classroom library is in here.
)

require (
  ...
)

// Use a local copy of the Go client library.
replace google.golang.org/api v0.139.0 => ../google-api-go-client

As another example, if you're using Node.js and npm, add the Node.js client library download (googleapis-classroom-1.0.4.tgz) as a local dependency in package.json:

{
  "name": "nodejs-classroom-example",
  "version": "1.0.0",
  ...
  "dependencies": {
    "@google-cloud/local-auth": "^2.1.0",
    "googleapis": "^95.0.0",
    "classroom-with-preview-features": "file:./googleapis-classroom-1.0.4.tgz"
  }
}

Then in your application, require the classroom-with-preview-features module in addition to regular dependencies, and instantiate the classroom service from that module:

const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const classroomWithPreviewFeatures = require('classroom-with-preview-features');

...

const classroom = classroomWithPreviewFeatures.classroom({
  version: 'v1',
  auth: auth,
});

...

Specify a preview API version

Regardless of whether you use a static or dynamic library, you must specify the preview version when making API calls to methods with preview capabilities.

The different available versions, and the features they include, are documented in the Classroom API Roadmap. The reference documentation for methods and fields also describe which version(s) the method or field is available in.

Specifying a version is done by setting the PreviewVersion field in requests. For example, to create a rubric with the Rubrics CRUD preview API, you would set previewVersion to V1_20231110_PREVIEW in the CREATE request:

rubric = service.courses().courseWork().rubrics().create(
            courseId=course_id,
            courseWorkId=coursework_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW",
            body=body
).execute()

Resources associated with a preview method call also contain the previewVersion used in the call as a read-only field, to help you understand which version you're using. For example, the response from the previous CREATE call contains the V1_20231110_PREVIEW value:

print(json.dumps(rubric, indent=4))
{
  "courseId": "123",
  "courseWorkId": "456",
  "creationTime": "2023-10-23T18:18:29.932Z",
  "updateTime": "2023-10-23T18:18:29.932Z",
  "id": "789",
  "criteria": [...],
  # The preview version used in the call that returned this resource.
  "previewVersion": "V1_20231110_PREVIEW",
  ...
}

HTTP requests

It is also possible to consume the Classroom API directly with HTTP.

If you make HTTP requests without a client library, you still need to enable preview features specify a preview version. This is done by setting a label with a X-Goog-Visibilities header and the aforementioned preview version as either a query parameter or POST body field (see the appropriate individual API reference documentation). For public previews, the label is DEVELOPER_PREVIEW.

For example, the following curl request makes a LIST call to the Rubrics service with the appropriate visibility label and preview version:

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_WORK_ID/rubrics?key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --compressed

You can also specify the preview version in the request body, for example when making a POST request:

curl --request PATCH \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_WORK_ID/rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]"}' \
  --compressed

The API for each HTTP request is described in the REST documentation.

Google Apps Script

It's possible to call preview APIs from Google Apps Script. However, there are a few differences from typical Apps Script usage.

You must configure your script to use whichever Google Cloud project you enrolled in the Developer Preview Program.
Advanced Services don't support preview methods, so you'll need to make requests directly with HTTP.
You must supply a label and preview version, as described in the preceding HTTP section.

See the corresponding quickstart to become familiar with Apps Script and get a basic project set up. Then follow these instructions to get started calling preview APIs:

Change the Cloud project used by the script

In Project Settings, click Change project and enter the Cloud project ID of whichever project you enrolled into the Developer Preview Program (by default, Apps Script scripts use a generic project). Only enrolled projects can call preview methods.

Configure HTTP requests

Next, configure the HTTP request of whichever method you'd like to call back in Editor. For example, in the quickstart, listing courses with the Classroom service looks like this:

function listCourses() {
  try {
    const response = Classroom.Courses.list();
    const courses = response.courses;
    if (!courses || courses.length === 0) {
      console.log('No courses found.');
      return;
    }
    for (const course of courses) {
      console.log('%s (%s)', course.name, course.id);
    }
  } catch (err) {
    // TODO: Developer to handle.
    console.log(err.message);
  }
}

The equivalent operation using HTTP directly is:

function listCourses() {
  const response = UrlFetchApp.fetch(
        'https://classroom.googleapis.com/v1/courses', {
        method: 'GET',
        headers: {'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()},
        contentType: 'application/json',
      });
  const data = JSON.parse(response.getContentText());
  if (data.error) {
    // TODO: Developer to handle.
    console.log(err.message);
    return;
  }
  if (!data.courses || !data.courses.length) {
    console.log('No courses found.');
    return;
  }
  for (const course of data.courses) {
    console.log('%s (%s)', course.name, course.id);
  }
}

When using Advanced services, the required OAuth scopes are inferred, but to make direct HTTP calls to Google APIs in Apps Script, you need to manually add the appropriate scopes.

In Project Settings, enable Show "appsscript.json" manifest file in editor. Back in Editor, add oauthScopes to the appscript.json file for whichever scopes you need. The scopes for a given method are listed in the reference page. For example, see the courses.courseWork.rubrics list method page.

The updated appscript.json file might look like this:

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/classroom.coursework.students",
    "https://www.googleapis.com/auth/classroom.courses",
    "https://www.googleapis.com/auth/spreadsheets.readonly",
    "https://www.googleapis.com/auth/spreadsheets"
  ]
}

Supply a label and preview version

Back in your script, ensure you've added the appropriate label and preview version as described in the preceding HTTP section. The example LIST call to the Rubrics service would look like:

function listRubrics() {
  const courseId = COURSE_ID;
  const courseWorkId = COURSE_WORK_ID;
  const response = UrlFetchApp.fetch(
         `https://classroom.googleapis.com/v1/courses/${courseId}/courseWork/${courseWorkId}/rubrics?previewVersion=V1_20231110_PREVIEW`, {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer ' + ScriptApp.getOAuthToken(),
          'X-Goog-Visibilities': 'DEVELOPER_PREVIEW'
        },
        contentType: 'application/json',
        muteHttpExceptions: true
      });
  const data = JSON.parse(response.getContentText());
  console.log(data)
  if (data.error) {
    // TODO: Developer to handle.
    console.log(error.message);
    return;
  }
  if (!data.rubrics || !data.rubrics.length) {
    console.log('No rubrics for this coursework!');
    return;
  }
  console.log(data.rubrics);
}