Drive API v2 & v3 comparison guide

Stay organized with collections Save and categorize content based on your preferences.

The latest version of the Google Drive API is v3. The performance in v3 is better because searches only return a subset of fields. Use the current version unless you need the Apps collection. If you're using v2 and your app doesn't use the Apps collection, consider migrating to v3. To migrate, see Migrate to Drive API v3. For a complete list of version differences, see the Drive API v2 & v3 comparison reference.

If you need the Apps collection, and want to continue to use v2, go to the Guide to Drive API v2 amendment to learn how some instructions in the v3 guides must be amended for v2 developers.

To learn more about the improvements to Drive API v3, you can watch the following video of Google engineers discussing the new API design.

V3 improvements

To optimize performance and reduce API behavior complexity, v3 provides these improvements over the previous API version:

  • Searches for files and shared drives don't return full resources by default, only a subset of commonly used fields gets returned. For more details about fields, see files.list and drives.list.
  • Almost all methods that return a response now require the fields parameter. For a list of all methods that require fields, see the API reference.
  • Resources that have duplicate capabilities were removed. Some examples:
    • The files.list method accomplishes the same functionality as the Children and Parents collections, so they're gone from v3.
    • The Realtime.* methods have been removed.
  • App Data isn't returned by default in searches. In v2, you can set the drive.appdata scope, and it returns application data from files.list and changes.list, but it slows performance. In v3, you set the drive.appdata scope, and also set the query parameter spaces=appDataFolder to request application data.
  • All update operations use PATCH instead of PUT.
  • To export Google Documents, use files.export.
  • The changes.list behavior is different. Instead of change ids, use opaque page tokens. To poll the change collection, first call changes.getStartPageToken for the initial value. For subsequent queries, changes.list returns the newStartPageToken value.
  • Update methods now reject requests that specify non-writable fields.
  • The v2 exportFormats and importFormats fields in About are lists of allowable import or export formats. In v3, they're MIME type maps of possible targets to all supported imports or exports.
  • The v2 appdata and appfolder aliases are now appDataFolder in v3.
  • The Properties collection is removed from v3. The Files resource has the properties field that contains true key-value pairs. The properties field contains public properties, and appProperties contain private properties, so the visibility field isn't needed.
  • The Files modifiedTime field updates the last time anyone modified the file. In v2, the modifiedDate field was only mutable on update if you set the setModifiedDate field.
  • The Files viewedByMeTime field doesn't automatically update.
  • To import Google Docs formats, you set the appropriate target mimeType in the resource body. In v2, you set ?convert=true.
  • Import operations return a 400 error if the format isn't supported.
  • Readers and commenters can't view permissions.
  • The me alias for permissions is gone.
  • Some functionality was available as part of the request resource, to instead be available as a request parameter. For example:
    • In v2, you can use children.delete to remove a child file from a parent folder.
    • In v3, you usefiles.update on the child with ?removeParents=parent_id in the URL.

Other differences

Fields and parameter names are different in v3. See tables below for all v2 to v3 changes. Some examples include:

  • The name property replaces title.
  • Time is the suffix for all date and time fields instead of Date.
  • List operations don't use the items field to contain the result set. The resource type provides a field for the results (such as files or changes).