Methods and Classes

This page documents all the methods and classes defined in the JavaScript client library.

Loading the client library

gapi.load(libraries, callbackOrConfig)

Asynchronously loads the gapi libraries requested. Use this method to load the gapi.client library.

Arguments:

Name	Type	Description
libraries	string	A colon (:) separated list of gapi libraries. Ex: "client:iframes".
callbackOrConfig	function|object	Either: A callback function that is called when the libraries have finished loading. An object encapsulating the various configuration parameters for this method. Only callback is required. Name Type Description callback function The function called when the libraries have finished loading. onerror function The function called if the libraries failed to load. timeout number The number of milliseconds to wait before calling the ontimeout function, if the libraries still haven't loaded. ontimeout function The function called if the libraries loading has taken more time than specified by the timeout parameter.

Example:

gapi.load('client', {
callback: function() {
// Handle gapi.client initialization.
initGapiClient();
},
onerror: function() {
// Handle loading error.
alert('gapi.client failed to load!');
},
timeout: 5000, // 5 seconds.
ontimeout: function() {
// Handle timeout.
alert('gapi.client could not load in a timely manner!');
}
});

Client setup

gapi.client.init(args)

Initializes the JavaScript client with API key, OAuth client ID, scope, and API discovery document(s).

Arguments:

Name	Type	Description
args	object	An object encapsulating the various arguments for this method. Every argument is optional. Name Type Description apiKey string The API Key to use. discoveryDocs array An array of discovery doc URLs or discovery doc JSON objects (Example). clientId string The app's client ID, found and created in the Google Developers Console. scope string The scopes to request, as a space-delimited string.

Returns:

Type		Description
goog.Thenable		The return value is a Promise-like goog.Thenable object that resolves when all initializations, including setting the API key, loading discovery documents, and initializing auth, are done.

gapi.client.load(urlOrObject)

Loads the client library interface to a particular API with discovery document URL or JSON object. Returns a Promise-like goog.Thenable object that resolves when the API interface is loaded. The loaded API interface will be in the form gapi.client.api.collection.method. For example, the Moderator API would create methods like gapi.client.moderator.series.list.

Arguments:

Name	Type	Description
urlOrObject	string | object	The Discovery Document URL or parsed Discovery Document JSON object (Example).

Returns:

Type		Description
goog.Thenable		The return value is a Promise-like goog.Thenable object that resolves when the API interface is loaded.

gapi.client.load(name, version, callback)

Deprecated. Please load APIs with discovery documents. Loads the client library interface to a particular API. If a callback is not provided, a goog.Thenable is returned. The loaded API interface will be in the form gapi.client.api.collection.method. For example, the Moderator API would create methods like gapi.client.moderator.series.list.

Arguments:

Name	Type	Description
name	string	The name of the API to load.
version	string	The version of the API to load.
callback	function	(optional) the function that is called once the API interface is loaded. If not provided, a goog.Thenable is returned.

gapi.client.setApiKey(apiKey)

Sets the API key for the application, which can be found in the Developer Console. Some APIs require this to be set in order to work.

Arguments:

Name	Type	Description
apiKey	string	The API key to set.

gapi.client.setToken(tokenObject)

Sets the authentication token to use in requests.

Arguments:

Name	Type	Description
tokenObject	object	An object containing the access_token to use in API requests. Name Type Description access_token string The access token granted to the user.

API requests

gapi.client.request(args)

Creates a HTTP request for making RESTful requests.

Arguments:

Name	Type	Description
args	object	An object encapsulating the various arguments for this method. The path is required, the rest are optional. The values are described in detail below. Name Type Description path string The URL to handle the request. method string The HTTP request method to use. Default is GET. params object URL params in key-value pair form. headers object Additional HTTP request headers. body string | object The HTTP request body (applies to PUT or POST).

Returns:

Type		Description
gapi.client.Request | undefined		The returned gapi.client.Request object implements goog.Thenable and can be used like a Promise that fulfills with the response object or rejects with a reason object.

gapi.client.Request

An object encapsulating an HTTP request. This object is not instantiated directly, rather it is returned by gapi.client.request. There are two ways to execute a request. We recommend that you treat the object as a promise and use the then method, but you can also use the execute method and pass in a callback.

gapi.client.Request.then(onFulfilled, onRejected, context)

For more information about using promises, see Using Promises.

gapi.client.Request.execute(callback)

Executes the request and runs the supplied callback on response.

Arguments:

Name	Type	Description
callback(jsonResp,rawResp)	function	The callback function which executes when the request succeeds or fails. jsonResp contains the response parsed as JSON. If the response is not JSON, this field will be false. rawResp is the HTTP response. It is JSON, and can be parsed to an object which includes body, headers, status, and statusText fields.

Batch API requests

gapi.client.newBatch()

Creates a batch object for batching individual requests.

Returns:

Type		Description
gapi.client.Batch | undefined		The returned gapi.client.Batch implements goog.Thenable interface and can be used like a Promise that fulfills with a batch response object and rejects with a reason object.

gapi.client.Batch

Represents an HTTP Batch operation. Individual HTTP requests are added with the add method and the batch can be executed using then or execute. We recommend that you treat the batch object as a promise and use then. This class defines the following methods:

gapi.client.Batch.add(request,opt_params)

Adds a gapi.client.Request to the batch.

Arguments:

Name	Type	Description
request	gapi.client.Request	The HTTP request to add to this batch. This parameter is required.
opt_params	Object	Optional extra parameters for this batch entry. Accepted fields are id and callback: Name Type Description id string Identifies the response for this request in the map of batch responses. If one is not provided, the system generates a random ID. callback(individualResponse, rawBatchResponse) function individualResponse is the response for this request only. Its format is defined by the API method being called. rawBatchResponse is the raw batch ID-response map as a string. It contains all responses to all requests in the batch.

gapi.client.Batch.then(onFulfilled, onRejected, context)

For more information about using promises, see Using Promises.

gapi.client.Batch.execute(callback)

Executes all requests in the batch. The supplied callback is executed on success or failure.

Name	Type	Description
callback(responseMap, rawBatchResponse)	function	The callback to execute when the batch returns. responseMap is an ID-response map of each requests response. rawBatchResponse is the same response, but as an unparsed JSON-string.