Google Drive SDK

Drive Platform Best Practices

The best practices described in this page can help you build high quality Google Drive apps.

Authenticating users

Use OAuth 2.0 authentication and the User Info service to authenticate new and existing users. Whenever you can avoid it, don't require users to create new passwords for your application.

Authorizing access

The OAuth 2.0 framework for Drive apps, as described in About Authorization, solves a lot of authorization challenges. However, some areas merit special attention, including handling revoked tokens and errors returned by the API. Also, all Drive apps should:

  • Always store the refresh token you get from Google in your database.
  • Always get the user ID from the User Info service, and index your database of refresh tokens based on this user ID. Indexing based on other values (such as an existing user record in your database) will not work.
  • Treat all Create New and Open with events like logins, retrieving the user ID and logging out the current session if it is for a different user.
  • If the user visits your app a second time, look up the refresh token from your database and store it in a server-side session.
  • Prominently display the currently logged-in user in your UI. This could include the profile picture and the name and email address from the User Info API.

Handling errors: revoked or invalid tokens

Google Drive apps should account for the API returning an HTTP 401 or HTTP 403 response when calling the Drive API. These errors could indicate any of:

  • Token expiry.
  • Token revocation. This would cause both the access token and the refresh token to stop working.
  • Token not authorized for needed scopes.
  • Request not authorized correctly with OAuth 2.0 protocol.

Token expiry can be handled by calling refreshToken(). If that call fails with an "Invalid Credentials" error, the issue is probably that the user has revoked access. For revoked access and all issues other than token expiry, the best remedy is to redirect the user through the OAuth dialog to re-grant access.

For a detailed code example of this case, see Send authorized requests and check for revoked credentials.

Handling exchanged authorization codes

The authorization code provided by Google's authorization servers can only be exchanged once. Exchanging the same authorization code again results in the token server returning an HTTP 400 response. To prevent the same code from being exchanged more than once, Google Drive apps can:

  • Redirect the user to another page on successful authentication, removing the authorization code from the URL.
  • Handle an HTTP 400 response from the token server and use stored credentials for the current user in the session.

Gracefully handling declined access requests

Prepare for cases where users click No Thanks in the OAuth dialog and decline access to your app. Rather than returning an unsightly error page (which is the result if you take no mitigating action), you can catch the access_denied string in the query parameter error and display a reasonable page in response.

Such a page could present a friendly parting message along with a link to your privacy policy and a meaningful explanation of why your app needs the information -- and, of course an option to be redirected back into the OAuth flow. If you can convince users that they'll get something valuable in return for access to their information, then they may decide to grant access.

Opening and creating files

All apps should treat Create new or Open with events like login operations. This means they should call the User Info service to determine the identity of the user and authorize appropriate access for that user's role.

Some other important guidelines:

  • Always call files.get when opening a file in order to get latest file details (such as title), update the last opened date, and check access.
  • Save revisions of files when it makes sense for your app -- such as at the end of editing session.
  • If you change the format of a file, save it to Drive as a new file instead of overwriting the existing file.

Auto-saving

It's a good idea to implement auto-save, which is a behavior that many users take for granted in an app. Save the head revision at intervals that work well for your app and its storage scheme. For auto-save, apps should explicitly set newRevision=false. For more information, see files.update.

Custom thumbnails and indexable text

If you are providing a custom thumbnail or indexable text for a file, you must refresh the corresponding metadata with each update of the file contents. For more information, see Manage file metadata.

Handling shared files

Expect that files will be shared by users -- sharing is one of Drive's most popular features. When opening files, your app should check the user’s role and render the UI appropriately, disabling edit for users with only read or comment privileges.

Improving performance

There are some basic measures you can take to improve performance with the Drive API. Using gzip compression and working with partial resources are described in detail in Performance Tips.

Handling API errors

Drive apps should catch and handle all errors that might be encountered when using the REST API. See Handling API Errors for a reference of the errors returned by the API.


Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.