The best practices described in this page can help you build high quality Google Drive apps.
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
stateparameter 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.
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.
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.