A JavaScript promise represents the result of an asynchronous operation. Promises can be in one of three states, pending, fulfilled, or rejected. To access a promise’s fulfilled value or rejection reason, register your handler to the promise’s then method.
The JavaScript client library provides a Promises/A+-conformant interface. We strongly recommend that you use promises instead of callbacks. Requests made using the promise interface are RESTful. Using promises also gives you elegant error handling and easy chaining, and the Google JavaScript promise interface fixes various small bugs and inconsistencies that were present in the older callback-based interface.
Requests created through gapi.client.request, gapi.client.newBatch, and registered API methods are “thenable.” gapi.client.load also returns a promise if a callback argument is not provided. Each of the requests has a then(opt_onFulfilled, opt_onRejected, opt_context) method that takes three optional parameters:
| Parameter | Type | Description |
|---|---|---|
opt_onFulfilled(response)
|
function | Optional fulfilled promise handler. |
opt_onRejected(reason)
|
function | Optional rejected promise handler. |
opt_context
|
object | Optional context for the handlers to execute in. |
Note: The promises in this library are resolved lazily. That means that no network requests are actually made until then is invoked. Once a promise is resolved or rejected with a value, the value does not change.
Note: We strongly recommended that you always provide a rejection handler. Rejections that your code does not handle are propagated as top-level exceptions. Rejection reasons can include application-level errors and network errors.
Fulfilled responses and application-level rejections are in the following format:
| Name | Type | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
response | reason
|
object |
An object containing information about the HTTP response.
|
Single requests example:
gapi.client.request({'path': '/plus/v1/people', 'query': 'John'}).then(function(response) {
// Handle response
}, function(reason) {
// Handle error
});
gapi.client.load('plus', 'v1').then(function() {
gapi.client.plus.people.search({'query': ''}).then(...);
});
When you create a request with the intention of adding it to a batch, do not invoke its then method until after the request has been added to the batch. If the then method is invoked before the request is added, the request is sent immediately instead of as part of the batch. You can invoke the requests’s then method before or after the batch’s then. The optional callback parameter to the add method has no effect when the batch object is treated as a promise.
Example:
var req1 = ... // Instantiate
var req2 = ... // Instantiate
var batch = gapi.client.newBatch();
batch.add(req1);
batch.add(req2);
req1.then(...);
batch.then(...);
req2.then(...);
Context parameter
Passing the context parameter is equivalent to binding the context value to the promise handlers by setting this in the handlers to point to the context.
Example:
var personFetcher = {
results: [],
fetch: function(name) {
gapi.client.request({path: '/plus/v1/people', params:{query: name}}).then(function(response) {
this.results.push(response.result);
}, function(reason) {
console.error(name, 'was not fetched:', reason.result.error.message);
}, this);
}
};
personFetcher.fetch('John');
The result parameter of the fulfilled promise value is equivalent to the first parameter in execute’s callback. To update your code to use promises, change your code as shown in the before and after examples below.
The following example shows using a callback:
gapi.client.request({
'path': 'plus/v1/people',
'params': {'query': name}
}).execute(function(resp, rawResp) {
processResponse(resp);
});
You can rewrite the example shown above to use a promise like the following:
gapi.client.request({
'path': 'plus/v1/people',
'params': {'query': name}
}).then(function(resp) {
processResponse(resp.result);
});