Drive Platform Best Practices
The best practices described in this page can help you build high quality Google Drive apps.
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.
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 400response 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.
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.getwhen 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.
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.
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.