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:auth2" . |
|||||||||||||||
callbackOrConfig |
function|object | Either:
|
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). If OAuth client ID and scope are provided, this function will load the gapi.auth2
module to perform OAuth. The gapi.client.init
function can be run multiple times, such as to set up more APIs, to change API key, or initialize OAuth lazily. Note that the scope
and clientId
parameters cannot be provided multiple times, since the gapi.auth2
module can only be initialized once.
Arguments:
Name | Type | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
args |
object | An object encapsulating the various arguments for this method. Every argument is optional.
|
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. This should be used if the token was obtained without using the gapi.auth2
authentication library (for instance, when using Firebase to authenticate users).
Arguments:
Name | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
tokenObject |
object | An object containing the access_token to use in API requests.
|
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.
|
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 :
|
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. |