Migrate to Google Drive API v3

If you have existing apps based on Drive API v2 you can migrate to Drive API v3. The differences between Drive API v3 and v2 are mainly changes to field names and removal of duplicate functionality.

Migrating from Google Drive API v2

Notable changes

  • Full resources are no longer returned by default. Use the fields query parameter to request specific fields to be returned. If left unspecified only a subset of commonly used fields are returned. Other methods require it to be specified. Check the reference docs for more information.
  • Duplicate and obsolete functionality has been removed. Examples:
    • The Children and Parents collections have been removed. Use files.list instead.
    • The Realtime.* methods have been removed. See the Realtime API documentation for alternatives.
  • A number of field and parameter names have changed and affects accessing fields in resources as well as q and fields expressions. Examples include:
    • The property name is now used in placed of title.
    • All date/time fields are now suffixed with Time instead of Date.
    • Results from list operations no longer use a generic items field to contain the result set. Results are now included in a field named for the corresponding resource type (e.g. files, changes, etc.).
  • All update operations now use PATCH instead of PUT
  • The exportLinks field has been removed from files. To export Google Documents, use the files.export method instead.
  • The general approach for changes.list has changed. Opaque page tokens are now used in place of change ids. To poll the change collection, first call changes.getStartPageToken for the initial value. For subsequent queries, uses the newStartPageToken value returned from changes.list.

Refer to the tables below for a full mapping of methods, parameters, and resource fields.


Method Alternative
apps.get n/a
apps.list n/a
changes.get n/a
children.delete files.update on the child with ?removeParents=parent_id
children.get files.list with ?q='parent_id'+in+parents
children.insert files.update on the child with ?addParents=parent_id
children.list files.list with ?q='parent_id'+in+parents
comments.insert comments.create
comments.patch comments.update
files.insert files.create
files.patch files.update
files.touch files.update with {'modifiedTime':'timestamp'}
files.trash files.update with {'trashed':true}
files.untrash files.update with {'trashed':false}
parents.delete files.update with ?removeParents=parent_id
parents.get files.get with ?fields=parents
parents.insert files.update with ?addParents=parent_id
parents.list files.get with ?fields=parents
permissions.getIdForEmail n/a
permissions.insert permissions.create
permissions.patch permissions.update
properties.delete PRIVATE: files.update with {'appProperties':{'key':null}}
PUBLIC: files.update with {'properties':{'key':null}}
properties.get PRIVATE: files.get with fields='appProperties'
PUBLIC: files.get with fields='properties'
properties.insert PRIVATE: files.update with {'appProperties':{'key':'value'}}
PUBLIC: files.update with {'properties':{'key':'value'}}
properties.list PRIVATE: files.get with fields='appProperties'
PUBLIC: files.get with fields='properties'
properties.update PRIVATE: files.update with {'appProperties':{'key':'value'}}
PUBLIC: files.update with {'properties':{'key':'value'}}
realtime.get n/a
realtime.update n/a
replies.insert replies.create
replies.patch replies.update
revisions.patch revisions.update


Method Parameter Alternative
about.get includeSubscribed n/a
about.get maxChangeIdCount n/a
about.get startChangeId n/a
changes.list includeDeleted includeRemoved
changes.list includeSubscribed=true restrictToMyDrive=false
changes.list includeSubscribed=false restrictToMyDrive=true
changes.list maxResults pageSize
changes.list startChangeId pageToken
comments.list maxResults pageSize
comments.list updatedMin startModifiedTime
files.copy convert Provide the target mimeType in the resource body
files.copy ocr OCR is enabled automatically for image imports
files.copy pinned keepRevisionForever
files.copy timedTextLanguage n/a
files.copy timedTextTrackName n/a
files.copy visibility=DEFAULT ignoreDefaultVisibility=false
files.copy visibility=PRIVATE ignoreDefaultVisibility=true
files.create convert Provide the target mimeType in the resource body
files.create ocr OCR is enabled automatically for image imports
files.create pinned keepRevisionForever
files.create timedTextLanguage n/a
files.create timedTextTrackName n/a
files.create visibility=DEFAULT ignoreDefaultVisibility=false
files.create visibility=PRIVATE ignoreDefaultVisibility=true
files.get projection n/a
files.get revisionId revisions.get
files.get updateViewedDate files.update with {'viewedByMeTime':'timestamp'}
files.generateIds maxResults count
files.list corpus=DEFAULT corpus=user
files.list corpus=DOMAIN corpus=domain
files.list maxResults pageSize
files.list projection n/a
files.update convert Provide the target mimeType in the resource body
files.update modifiedDateBehavior The modified date is set automatically if not provided in the resource body.
files.update newRevision n/a
files.update ocr OCR is enabled automatically for image imports
files.update pinned keepRevisionForever
files.update setModifiedDate n/a
files.update timedTextLanguage n/a
files.update timedTextTrackName n/a
files.update updateViewedDate files.update with {'viewedByMeTime':'timestamp'}
permissions.create sendNotificationEmails sendNotificationEmail
replies.list maxResults pageSize


Resource Field Alternative
About additionalRoleInfo n/a
About domainSharingPolicy n/a
About etag n/a
About features n/a
About languageCode n/a
About largestChangeId changes.getStartPageToken
About maxUploadSizes maxImportSizes and maxUploadSize
About name user.displayName
About permissionId user.permissionId
About quotaBytesByService n/a
About quotaType Indicated by the presence or absence of storageQuota.limit
About remainingChangeIds n/a
About rootFolderId files.get with fileId=root and ?fields=id
About selfLink n/a
About isCurrentAppInstalled appInstalled
About quotaBytesTotal storageQuota.limit
About quotaBytesUsed storageQuota.usageInDrive
About quotaBytesUsedAggregate storageQuota.usage
About quotaBytesUsedInTrash storageQuota.usageInDriveTrash
ChangeList etag n/a
ChangeList items changes
ChangeList largestChangeId newStartPageToken
ChangeList nextLink nextPageToken
ChangeList selfLink n/a
Change deleted removed
Change id n/a
Change selfLink n/a
Change modificationDate time
CommentList nextLink nextPageToken
CommentList selfLink n/a
CommentList items comments
Comment context.type quotedFileContent.mimeType
Comment context.value quotedFileContent.value
Comment createdDate createdTime
Comment fileId n/a
Comment fileTitle files.get with ?fields=name
Comment modifiedDate modifiedTime
Comment selfLink n/a
Comment status resolved
FileList etag n/a
FileList items files
FileList nextLink nextPageToken
FileList selfLink n/a
File alternateLink webViewLink
File appDataContents spaces
File copyable capabilities.canCopy
File createdDate createdTime
File defaultOpenWithLink n/a
File downloadUrl files.get with ?alt=media
File editable capabilities.canEdit
File embedLink n/a
File etag n/a
File exportLinks files.export
File fileSize size
File imageMediaMetadata.date imageMediaMetadata.time
File indexableText.text contentHints.indexableText
File labels.hidden n/a
File labels.restricted viewersCanCopyContent
File labels.starred starred
File labels.trashed trashed
File labels.viewed viewedByMe
File lastModifyingUserName lastModifyingUser.displayName
File lastViewedByMeDate viewedByMeTime
File markedViewedByMeDate n/a
File modifiedByMeDate modifiedByMeTime
File modifiedDate modifiedTime
File openWithLinks n/a
File ownerNames owners.displayName
File selfLink n/a
File shareable capabilities.canShare
File sharedWithMeDate sharedWithMeTime
File thumbnail.image contentHints.thumbnail.image
File thumbnail.mimeType contentHints.thumbnail.mimeType
File title name
File userPermission ownedByMe, capabilities.canEdit, capabilities.canComment
File webViewLink n/a
PermissionList etag n/a
PermissionList items permissions
PermissionList selfLink n/a
Permission additionalRoles role
Permission authKey n/a
Permission etag n/a
Permission name displayName
Permission selfLink n/a
Permission value emailAddress or domain
Permission withLink=true allowFileDiscovery=false
Permission withLink=false allowFileDiscovery=true
ReplyList items replies
ReplyList nextLink nextPageToken
ReplyList selfLink n/a
Reply createdDate createdTime
Reply modifiedDate modifiedTime
Reply replyId id
Reply verb action
RevisionList etag n/a
RevisionList items revisions
RevisionList selfLink n/a
Revision downloadUrl revisions.get with ?alt=media
Revision etag n/a
Revision exportLinks n/a
Revision fileSize size
Revision lastModifyingUserName lastModifyingUser.displayName
Revision modifiedDate modifiedTime
Revision pinned keepForever
Revision publishedLink n/a
Revision selfLink n/a
User isAuthenticatedUser me
User picture.url photoLink

Other changes

  • Update methods now reject requests which specify non-writable fields.
  • The fields query parameter should be specified for methods which return a response.
  • The exportFormats and importFormats fields in About are now maps of source MIME type to target MIME types.
  • The appdata and appfolder aliases have been replaced with appDataFolder.
  • The drive.appdata scope no longer causes application data files to be returned from files.list and changes.list. Use the query parameter ?spaces=appDataFolder to request application data.
  • Properties are now maps in File resources. Public properties are in the properties field while private properties are in appProperties.
  • Property queries now use two separate fields with no explicit visibility parameter:
    properties has {key='k' and value='v'}
    appProperties has {key='k' and value='v'}
  • The File modifiedTime field is now updated intelligently based on the fields being modified. Clients can also set it explicitly.
  • The File viewedByMeTime field no longer updated automatically.
  • Imports to Google Docs formats are now requested by setting the appropriate target mimeType in the resource body, rather than specifying ?convert=true.
  • Import operations will return a 400 error if the format is not supported.
  • Readers and commenters can no longer view permissions.
  • The me alias for permissions has been removed.

Send feedback about...

Google Drive API
Google Drive API
Need help? Visit our support page.