diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..1aed3a5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,25 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: '' +assignees: '' + +--- + +*Important gapi.auth2 notice*: gapi.auth2 has been deprecated and replaced with Google Identity Services. Please see https://developers.google.com/identity/sign-in/web/deprecation-and-sunset for more information. If you have questions related to authentication/authorization please look at the associated documentation or post questions on Stack Overflow with the google-oauth tag. + +**Summary** +Describe your issue here. + +**Browser(s)/Version(s)** +List browsers and versions affected + +**Expected Behavior** +Tell us what should happen. + +**Actual Behavior** +Tell us what actually happened. + +**Steps to Reproduce** +Please include steps and code samples to aid in issue reproduction(html/javascript). diff --git a/README.md b/README.md index 22a9d77..ea482ed 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,6 @@ developers. It offers simple, flexible access to many Google APIs. The JavaScript client library [supports these Google APIs](https://developers.google.com/apis-explorer/#p/). -The library supports [OAuth 2 authentication](https://developers.google.com/api-client-library/javascript/features/authentication). - If you use TypeScript, you can install [`@types/gapi`](https://www.npmjs.com/package/@types/gapi) for autocompletion. # Documentation @@ -24,7 +22,6 @@ If you use TypeScript, you can install [`@types/gapi`](https://www.npmjs.com/pac - [Auth](docs/auth.md) - [Batch](docs/batch.md) -- [CORS](docs/cors.md) - [Discovery Documents](docs/discovery.md) - [FAQ](docs/faq.md) - [Promises](docs/promises.md) @@ -33,4 +30,3 @@ If you use TypeScript, you can install [`@types/gapi`](https://www.npmjs.com/pac ## Links - [Discussions](https://github.com/google/google-api-javascript-client/issues) -- [Historical Announcements](http://google-api-javascript-client.blogspot.com/) diff --git a/docs/README.md b/docs/README.md index 386d50f..0d5d2b9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,7 +9,6 @@ access to many Google APIs. - [Getting Started](start.md) - [Auth](auth.md) - [Batch](batch.md) -- [CORS](cors.md) - [Discovery Documents](discovery.md) - [FAQ](faq.md) - [Promises](promises.md) diff --git a/docs/auth.md b/docs/auth.md index 708d063..5e687bc 100644 --- a/docs/auth.md +++ b/docs/auth.md @@ -1,123 +1,3 @@ # Authentication -[](#top_of_page)Overview ------------------------- - -To access a user's private data, your application must work with Google's policies for authentication and authorization. - -Google defines two levels of API access: - - - - - - - - - - - - - - - - - -
- Level - - Description - - Requires: -
- Simple - - API calls do not access any private user data - - API key -
- Authorized - - API calls can read and write private user data, or the - application's own data - - API key plus OAuth 2.0 credentials (different for - different application types) -
- -[](#top_of_page)Getting access keys for your application --------------------------------------------------------- - -To get access keys, go to the [Google Developers Console](https://console.developers.google.com) and specify your application's name and the Google APIs it will access. For simple access, Google generates an API key that uniquely identifies your application in its transactions with the Google Auth server. - -For authorized access, you must also tell Google your website's protocol and domain. In return, Google generates a client ID. Your application submits this to the Google Auth server to get an OAuth 2.0 access token. - -For detailed instructions for this process, see the [Getting started](start.md) page. - -See below for details and examples of how to use these credentials in your application. - -[](#top_of_page)Simple access using the API key ------------------------------------------------ - -The API key identifies your application for requests that don't require authorization. - -Whether or not your application requires authorized access, your code should call `gapi.client.init` with the `apiKey` parameter. - -```js -gapi.client.init({ 'apiKey': 'YOUR_API_KEY', ... -}).then(...) -``` - -For a complete example of simple API access, follow [this link](samples.md#LoadinganAPIandMakingaRequest). - -[](#top_of_page)Authorized access ---------------------------------- - -To access a user's personal information, your application must work with Google's OAuth 2.0 mechanism. - -### OAuth 2.0 basics - -You may want to start with this overview of [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/accounts/docs/OAuth2). - -Behind the scenes, the OAuth 2.0 mechanism performs a complex operation to authenticate the user, the application, and the Google Auth server. The components of the JavaScript client library manage this process for you, so that all your code has to do is pass in the following objects: - -* The client ID you received when you registered your application -* The scope object that specifies which data your application will use - -### About scope - -The scope object defines the level of access to a particular API that your application will use. For more information about how scopes work, refer to [this OAuth 2.0 documentation](https://developers.google.com/accounts/docs/OAuth2.html). The scope is a **space delimited string**. The following example represents read-only access to a user's Google Drive: - -https://www.googleapis.com/auth/drive.readonly - -### OAuth 2.0 authorization flow - -The JavaScript client library uses the [OAuth 2.0 client-side flow](https://developers.google.com/accounts/docs/OAuth2UserAgent) for making requests that require authorization. If you would like to see what this looks like in action, check out [Google's OAuth 2.0 Playground](https://developers.google.com/oauthplayground/). - -OAuth 2.0 authorization in the JavaScript client library proceeds as follows: - -1. The user clicks a "login" link. -2. The browser shows a popup that allows the user to authenticate and authorize the web application. -3. After successful authorization, the browser redirects the user back to the calling application (your application). -4. The callback saves the authorization token and closes the popup. - -After this, the user is signed in to your application, and the application is authorized to access the user's personal data. The user's sign-in state is persistent across sessions, so the next time the user opens your application, the user is automatically signed in. - -[](#top_of_page)Auth example ----------------------------- - -See the [auth example](samples.md#authorizing-and-making-authorized-requests) on the Samples page. - -[](#top_of_page)Making a request with CORS ------------------------------------------- - -To make an authenticated [CORS](http://www.w3.org/TR/cors/) request, you can add the OAuth 2.0 access token to the request header or add it as a URL parameter. For details, read the [CORS documentation](cors.md). - -[](#top_of_page)The standalone auth client ------------------------------------------- - -Your application can also use a subset of the full JavaScript client library that performs authentication and nothing else. It includes only the `gapi.auth` methods. - -Use the standalone auth client in web applications that will run in environments with full CORS support, such as Chrome extensions and mobile browsers. If your application may run on browsers which do not support CORS, or if you want to use other features of the JavaScript library, use the standard JavaScript client. - -For information about how to load and use the auth client, see the [CORS documentation](cors.md). +gapi.auth2 has been deprecated and replaced with Google Identity Services. Please see https://developers.google.com/identity/sign-in/web/deprecation-and-sunset for more information. If you have questions related to authentication/authorization please look at the associated documentation or post questions on Stack Overflow with the google-oauth tag. diff --git a/docs/batch.md b/docs/batch.md index eae199b..a612633 100644 --- a/docs/batch.md +++ b/docs/batch.md @@ -7,12 +7,12 @@ The JavaScript client library supports batching HTTP requests to make multiple A The JavaScript client library defines an object called `Batch`. You can start by instantiating this object: ```js -var batch = gapi.client.newBatch(); +const batch = gapi.client.newBatch(); ``` ## Adding requests to the batch -Use the `Batch` object's [`add`](reference.md#----gapiclientbatchaddrequestopt_params--) method to add individual HTTP requests. The `add` method supports one optional parameter: +Use the `Batch` object's [`add`](reference.md#----gapiclientbatchaddrequestopt_params--) method to add individual HTTP requests. Only requests created via [discovery](discovery.md) should be added to a batch. The `add` method supports one optional parameter: @@ -49,19 +49,18 @@ Use the `Batch` object's [`add`](reference.md#----gapiclientbatchaddrequestopt_p Example: ```js -var searchRequest = function(name) { - return gapi.client.request({ - 'path': 'plus/v1/people', - 'params': {'query': name} - }); -}; -var searchAlvin = searchRequest('Alvin'); -var searchSimon = searchRequest('Simon'); +const getMe = gapi.client.people.people.get({ + 'resourceName': 'people/me' +}); + +const getYou = gapi.client.people.people.get({ + 'resourceName': 'people/you' +}); // Adding just the request -batch.add(searchAlvin); +batch.add(getMe); // Adding the request with an ID -batch.add(searchSimon, {'id': 'searchSimon'}); +batch.add(getYou, {'id': 'getYou'}); ``` ## Executing a batch diff --git a/docs/cors.md b/docs/cors.md deleted file mode 100644 index 494d9cb..0000000 --- a/docs/cors.md +++ /dev/null @@ -1,95 +0,0 @@ -# How to use CORS to access Google APIs - -Google APIs support requests and responses using [Cross-origin Resource Sharing](http://www.w3.org/TR/cors/) (CORS). You do not need to load the complete JavaScript client library to use CORS. If you want your application to access a user's personal information, however, it must still work with Google's OAuth 2.0 mechanism. To make this possible, Google provides the standalone auth client — a subset of the JavaScript client. - -This page explains how to use the standalone auth client and CORS to access Google APIs. - -Loading the standalone auth client ----------------------------------- - -The standalone Auth client can be loaded with the JavaScript client's `load` function: - -```html - - -``` - -Using CORS ----------- - -To start, you may want to check out this excellent HTML 5 Rocks [tutorial](http://www.html5rocks.com/en/tutorials/cors/) for an overview on how to use CORS. - -Use [XMLHttpRequest2](http://www.w3.org/TR/XMLHttpRequest/) to make CORS requests. - -**Note:** The examples in this documentation use the `XMLHttpRequest` constructor. Please be sure to check [browser compatibility](http://caniuse.com/#search=cors) for all the browsers you want to support. For cross-browser compatibility, use a helper function such as `createCORSRequest` from the tutorial linked to above. - -A CORS request to a Google API is similar to a [REST](/api-client-library/javascript/reference/referencedocs#gapiclientrequest) request. The URL for a CORS request follows this pattern: - -``` -https://www.googleapis.com + - REST path + URL Params -``` - -**Example:** here is a REST request: - -```js -var restRequest = gapi.client.request({ - 'path': 'https://people.googleapis.com/v1/people/me/connections', - 'params': {'sortOrder': 'LAST_NAME_ASCENDING'} -}); -``` - -And here is the equivalent CORS request: - -```js -var xhr = new XMLHttpRequest(); -xhr.open('GET', 'https://people.googleapis.com/v1/people/me/connections?sortOrder=LAST_NAME_ASCENDING'); -``` - -Request headers are added to the request using [XMLHttpRequest.setRequestHeader](http://www.w3.org/TR/XMLHttpRequest/#the-setrequestheader-method). - -The request body is sent using the [XMLHttpRequest.send](http://www.w3.org/TR/XMLHttpRequest/#the-send-method) method. - -You can register callbacks by adding event listeners on the `load` and `error` events. -Follow this link for information about [XMLHttpRequest events](http://www.w3.org/TR/XMLHttpRequest/#events) - -Making authenticated requests ------------------------------ - -To obtain an access token for making authenticated requests, use the same `gapi.auth2` methods from the standard JavaScript Client or the auth-only client. For instructions on obtaining an access token, see the [Authentication page](/api-client-library/javascript/features/authentication). There are two ways to make an authenticated request with CORS: - -* Send the access token in the Authorization [request header](http://www.w3.org/TR/XMLHttpRequest/#the-setrequestheader-method). -* Include the access token as the `access_token` parameter in the URL. - -To retrieve an access token, call the `getAuthResponse()` method of a `GoogleUser` object. - -The format of the [OAuth 2.0 token](/api-client-library/javascript/reference/referencedocs#OAuth20TokenObject) is described in the [Methods and classes](/api-client-library/javascript/reference/referencedocs) document. - -### Example 1: Using the request header - -```js -var user = gapi.auth2.getAuthInstance().currentUser.get(); -var oauthToken = user.getAuthResponse().access_token; -var xhr = new XMLHttpRequest(); -xhr.open('GET', - 'https://people.googleapis.com/v1/people/me/connections'); -xhr.setRequestHeader('Authorization', - 'Bearer ' + oauthToken); -xhr.send(); -``` - -### Example 2: Using the URL parameter - -```js -var user = gapi.auth2.getAuthInstance().currentUser.get(); -var oauthToken = user.getAuthResponse().access_token; -var xhr = new XMLHttpRequest(); -xhr.open('GET', - 'https://people.googleapis.com/v1/people/me/connections' + - '?access_token=' + encodeURIComponent(oauthToken)); -xhr.send(); -``` \ No newline at end of file diff --git a/docs/faq.md b/docs/faq.md index d04e243..9901843 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -4,28 +4,6 @@ The JavaScript client library does not support local pages and the `file://` protocol. The application must be hosted on a server (can be localhost). -### Does the JavaScript client library set authentication cookies? +### Is it possible to use the JavaScript client library in a Chrome Extension? -The JavaScript client library does not write any auth cookies. `gapi.auth.getToken` and `gapi.auth.setToken` provide access to the auth token. - -### How do I refresh the auth token, and how often should I do it? - -Refresh the token by calling `gapi.auth.authorize` with the client ID, the scope and `immediate:true` as parameters. - -Currently, the auth token expires after one hour. A common practice is to refresh the auth token after 45 minutes. If you refresh the auth token too often (every five minutes, for example) you will run into the refresh rate limit. (The rate limit is per-user, so the number of user connections is not an issue.) - -The auth token's `expires_in` field will tell you the token's time to expiration. - -The [authSample.html file](https://github.com/google/google-api-javascript-client/blob/master/samples/authSample.html) contains one example of code that handles signin and signout but not token refreshes. - -### Is it possible to use the JavaScript client library in an installed application? - -At this time, the JavaScript client library supports web applications only. For mobile devices you can use one of our other client libraries like the one for [Objective-C](http://code.google.com/p/google-api-objectivec-client/) - -### How can I use the JavaScript client library to log the user out of my application? - -The JavaScript client library does not directly support logging the user out of the application. Typically, developers include a logout link to https://accounts.google.com/logout. - -Since logging out of the application also logs the user out of the Google account, it is not recommended to log the user out unless the user requests this explicitly. - -For a workaround that allows your application to log the user out programatically, see [this topic](https://groups.google.com/forum/?fromgroups=#!topic/google-api-javascript-client/PCs8xXV4wxk) in the JavaScript client library discussion group. +Chrome Extensions using Manifest v3 do not allow [remotely hosted code](https://developer.chrome.com/docs/extensions/mv3/intro/mv3-overview/#remotely-hosted-code), so the Javascript client library cannot be used in this case. diff --git a/docs/promises.md b/docs/promises.md index 9de1612..9bae8b5 100644 --- a/docs/promises.md +++ b/docs/promises.md @@ -224,9 +224,6 @@ personFetcher.fetch('John'); ## Migrating from callbacks to promises -Migrating from callbacks to promises ------------------------------------- - The `result` parameter of the fulfilled promise value is equivalent to the first parameter in [`execute`](/api-client-library/javascript/reference/referencedocs#gapiclientRequestexecute)'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: @@ -249,4 +246,4 @@ gapi.client.request({ }).then(function(resp) { processResponse(resp.result); }); -``` \ No newline at end of file +``` diff --git a/docs/reference.md b/docs/reference.md index dd5c501..23e728c 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -38,7 +38,7 @@ @@ -147,13 +147,7 @@ alert('gapi.client could not load in a timely manner!');

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. + API discovery document(s).

Arguments: @@ -275,7 +269,7 @@ alert('gapi.client could not load in a timely manner!');

Loads the client library interface to a particular API with - discovery document + discovery document URL or JSON object. Returns a Promise-like goog.Thenable @@ -458,9 +452,7 @@ alert('gapi.client could not load in a timely manner!'); 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). + Sets the authentication token to use in requests.

Arguments: @@ -908,4 +900,4 @@ alert('gapi.client could not load in a timely manner!');

A colon (:) separated list of gapi libraries. Ex: - "client:auth2". + "client:iframes".
- \ No newline at end of file + diff --git a/docs/samples.md b/docs/samples.md index 3302c49..e262384 100644 --- a/docs/samples.md +++ b/docs/samples.md @@ -1,6 +1,6 @@ # Samples -This page provides three detailed examples which demonstrate the library's functionality. Browse the [project source](https://github.com/google/google-api-javascript-client/tree/master/samples) for additional samples. +This page provides three detailed examples which demonstrate the library's functionality. Additional samples(including authenticated/authorized requests) can be found in API specific documentation such as the [Google Drive API Quick Start](https://developers.google.com/drive/api/quickstart/js). Loading an API and Making a Request ----------------------------------- @@ -41,51 +41,3 @@ This snippet shows how to load an API and make a request. In this case, the requ ``` - -## Authorizing and Making Authorized Requests - -The following sample demonstrates how to get "authorized" access to a Google API using OAuth 2.0. See the full sample at [authSample.html](https://github.com/google/google-api-javascript-client/blob/master/samples/authSample.html). - -It's called "authorized" access because the user must give the application direct authorization to use personal data. Simple web-based applications using JavaScript usually get this authorization the way this example does: by displaying button for the user to click. This action triggers a call to a Google auth server, which pops up a standard authorization dialog. For details, see the [Authentication page](auth.md). - -**Note:** Here we use `gapi.load('client:auth2', ...)` to load both the `client` module (for dealing with API requests) and the `auth2` module (for dealing with OAuth 2.0) upfront. The `gapi.client.init` fuction lazily loads `auth2` if it is needed. If you are sure your app needs auth, loading the two modules `'client:auth2'` together before you call `gapi.client.init` will save one script load request. - -To make `gapi.client.init` set up OAuth correctly, you would have to assign the `clientID` variable the client ID generated when you registered your application (for instructions see [Integrating Google Sign-In into your web app](https://developers.google.com/identity/sign-in/web/sign-in)). The other parameter is `scope`, which in this case is just the scope for user profile permission. - -When the user clicks **Authorize**, the `gapi.auth2.getAuthInstance().signIn()` function is called, which shows user a popup window to let user authorize. Note that the `gapi.auth2.getAuthInstance().signIn()` can be only called from a user interaction context for most browsers (i.e. do not call it when your app starts, but call it in a button click handler). - -**Note:** when you authorize your application using Oauth 2.0, you do not also need to set the API key as in the first example. However, it is a good practice to do so, in case your code ever expands to handle unauthorized requests. - -## Loading the Library Asychronously - -The following code snippet shows how to load the library without blocking UI loading. (The `onreadystatechange` is used to support old versions of IE.) - -```html - - - - - - -
- - -``` - -## Putting it all together - -The file [authSample.html](https://github.com/google/google-api-javascript-client/blob/master/samples/authSample.html) expands on the concepts on this page and provides a more complete example of making an authenticated call to the Google People API. diff --git a/docs/start.md b/docs/start.md index e7ebe12..0973f55 100644 --- a/docs/start.md +++ b/docs/start.md @@ -8,14 +8,14 @@ You can use the JavaScript client library to interact with Google APIs, such as There are several ways to use the JavaScript client library to make API requests, but they all follow the same basic pattern: 1. The application loads the JavaScript client library. -2. The application initializes the library with API key, OAuth client ID, and [API Discovery Document(s)](https://developers.google.com/api-client-library/javascript/features/discovery). +2. The application initializes the library with API key, OAuth client ID, and [API Discovery Document(s)](discovery.md). 3. The application sends a request and processes the response. -The following sections show 3 common ways of using the JavaScript client library. +The following sections show 2 common ways of using the JavaScript client library. ### Option 1: Load the API discovery document, then assemble the request. -The following example assumes the user has already signed in. For a full example of how to sign in a user, see the [full auth sample](https://developers.google.com/api-client-library/javascript/samples/samples#authorizing-and-making-authorized-requests). +The following example assumes the user has already signed in. For a full example of how to sign in a user, see the [full auth sample](https://github.com/google/google-api-javascript-client/blob/master/docs/samples.md#authorizing-and-making-authorized-requests). ```html @@ -76,15 +76,13 @@ gapi.load('client', start); ``` -### Option 3: Use CORS - -Google APIs support [CORS](http://www.w3.org/TR/cors/). If your application needs to do media uploads and downloads, it should use CORS. See the [CORS Support](https://developers.google.com/api-client-library/javascript/features/cors) page for details. - [](#top_of_page)Supported environments -------------------------------------- The JavaScript client library works with the same browsers supported by [Google Apps](https://support.google.com/a/answer/33864) except that mobile browsers are currently not fully supported. It only works within HTML documents with a `` element served using the `https` _(preferred)_ and `http` protocols. However, `