Preview methods in Add-ons early access

API methods in early access or private preview programs are private, meaning that they aren't exposed in the standard client libraries and may not be accessible by default over HTTP. This page describes how you can access these preview methods.

This document discusses four options for consuming the preview API:

  1. Google-provided static client libraries.
  2. Dynamically generated client libraries.
  3. Direct HTTP requests.
  4. Your own custom client library.

Using Google-provided static or dynamically generated libraries are the recommended way to use the API.

Static libraries

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

You may 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 methods.

For 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-addons": "file:./googleapis-classroom-1.0.4.tgz"
  }
}

Then in your application, require the classroom-with-addons 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 classroomWithAddons = require('classroom-with-addons');

...

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

...

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 may 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>

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

classroom_service_with_rubrics = googleapiclient.discovery.build(
  serviceName="classroom",
  version="v1",
  credentials=credentials,
  static_discovery=False,
  discoveryServiceUrl=f"https://classroom.googleapis.com/$discovery/rest?labels=ADD_ONS_ALPHA&key=ABCXYZ")

See the individual Google API client library documentation for details on each language. The important distinction for working with preview APIs is specifying the appropriate label. In this preview that label is ADD_ONS_ALPHA.

HTTP requests

If you make HTTP requests without a client library, be sure to include the label (ADD_ONS_ALPHA) as a X-Goog-Visibilities header.

For example, to view all attachments created by an add-on under a post, use the following curl request:

curl \
  'https://classroom.googleapis.com/v1/courses/[courseId]/posts/[postId]/addOnAttachments?key=[YOUR_API_KEY]' \
  --header 'X-Goog-Visibilities: ADD_ONS_ALPHA' \
  --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
  --header 'Accept: application/json' \
  --compressed

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

Custom client libraries

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.