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
, seefiles.list
anddrives.list
. - Almost all methods that return a response now require the
fields
parameter. For a list of all methods that requirefields
, see the API reference. - Resources that have duplicate capabilities were removed. Some examples:
- The
files.list
method accomplishes the same functionality as theChildren
andParents
collections, so they're gone from v3. - The
Realtime.*
methods have been removed.
- The
- App Data isn't returned by default in searches. In v2, you can set the
drive.appdata
scope, and it returns application data fromfiles.list
andchanges.list
, but it slows performance. In v3, you set thedrive.appdata
scope, and also set the query parameterspaces=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 callchanges.getStartPageToken
for the initial value. For subsequent queries,changes.list
returns thenewStartPageToken
value. - Update methods now reject requests that specify non-writable fields.
- The v2
exportFormats
andimportFormats
fields inAbout
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
andappfolder
aliases are nowappDataFolder
in v3. - The
Properties
collection is removed from v3. TheFiles
resource has theproperties
field that contains true key-value pairs. Theproperties
field contains public properties, andappProperties
contain private properties, so the visibility field isn't needed. - The
Files
modifiedTime
field updates the last time anyone modified the file. In v2, themodifiedDate
field was only mutable on update if you set thesetModifiedDate
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 use
files.update
on the child with?removeParents=parent_id
in the URL.
- In v2, you can use
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 replacestitle
. Time
is the suffix for all date and time fields instead ofDate
.- List operations don't use the
items
field to contain the result set. The resource type provides a field for the results (such asfiles
orchanges
).