This page describes how you can access Classroom API preview features and specify preview versions.
The two considerations when using preview features when compared to the stable v1 API are:
- 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. 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_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_ID/rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"criteria":"[...]", "preview_version": "V1_20231110_PREVIEW"}' \
--compressed
The API for each HTTP request is described in the REST documentation.