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 and Google's identity APIs 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. All Drive Apps should:

  • Treat all Create New and Open with events like potential logins. Some users may have multiple accounts. If the user ID in the state parameter does not match the current session, you may need to end the current session for your app and log in as the requested user.

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 refreshing the credentials. 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.

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:

  • Save revisions of files when it makes sense for your app -- such as at the end of editing session.
  • If your app converts the format of a file, save it to Drive as a new file instead of overwriting the existing file.

Custom thumbnails and indexable text

If you are providing a custom thumbnail or indexable text for a file, you must continue to provide updated data 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.

Send feedback about...

Need help? Visit our support page.