Skip to content

Latest commit

 

History

History
903 lines (897 loc) · 21.1 KB

reference.md

File metadata and controls

903 lines (897 loc) · 21.1 KB
Raw

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.