DBX File Access Guide

Welcome! If you’re trying to access Dropbox files through the API, then you’re in the right place. This guide is for learning to interact with files by using the Dropbox API.

When building with the Dropbox API, every file is represented by metadata. Every single file from spreadsheets to cat pictures to shortcuts can be thought of as a JSON object with a set of fields that provide information about the file. Folders also have metadata, which we’ll cover in the List Folder Content section below.  

When working with files or folders using the Dropbox API, there are specific fields that are commonly used. That’s a great place to start our understanding of file metadata.

Let’s take a look at the file data for random_cartoon.mp4:

Please refer to the FileMetadata type under the /files/get_metadata documentation for exact property descriptions. We’re leaving out a few of them to focus on certain core properties:

• .tag is used to quickly distinguish between a file and folder by identifying the underlying type
• id is used as a unique reference to a specific file
  • Note that a new file with the same file name would still be assigned a new id
• server_modified is used to determine when the file was last changed
• rev is used as a reference to specific versions of a file to help with things like change detection
• content_hash can be used to verify a local version of a file matches the one in Dropbox

Optional fields are used to track additional information about the state of a file or folder. For example, if random_cartoon.mp4 was placed inside a shared folder and then locked for editing, then our metadata would contain both sharing_info and file_lock_info.

When using the Dropbox API to interact with a specific file, most /files/ endpoints require a path that points to a specific file. There are multiple ways to reference a file that can be used as path parameter:

1. File path (e.g. /Pictures/cats/cat_in_box.png)
    - Most “human readable” reference
    - Dependent on the file name and location staying the same
    - Best choice for referencing a file by name in a specific location

2. File id (e.g. id:odTlUvbpIEFAAAAAAAAGOQ)
    - Unique file reference that persists if files are moved or renamed
    - Useful for apps referencing files that are moved around
    - Best choice for reliable, accurate reference to a specific file

3. File revision (e.g. rev:015a01044acb99900000001aa8954d0)
    - References a specific version of a file
    - Useful for version control, restoring deleted files, and managing conflicting copies
    - Best choice for referencing a file at a specific point in time

4. Namespace-relative file path (e.g. ns:1522576049/cats/cat_in_box.png)
    - References a file in a specific namespace, which is a unique permission space
    - Useful for referencing files in shared folders mounted in different locations for each user
    - Best choice for admins using the Dropbox-API-Select-Admin header

Consider how your app needs to interact with Dropbox files and choose the best file reference for your needs.

You can list contents of a Dropbox folder with the /files/list_folder endpoint, which accepts a folder’s path and returns the content of that folder in an entries array along with a cursor for retrieving additional results with /files/list_folder/continue. Using the recursive argument will return content of subfolders, which simplifies traversal.

In addition to a folder’s path (e.g. /Homework/math), the path parameter will also accept:

• a folder’s id (e.g. id:odTlUvbpIEAAAAAAAAAGGQ)
• a folder path scoped to a specific namespace (e.g. ns:1521576049/Homework/math)

Example /files/list_folder output:

When listing folder content, you should always check the has_more flag. If it’s true, then your results have been paginated and you’ll need to call /files/list_folder/continue with the cursor from your response.  

Access Rights

The access rights of the content is returned in the sharing_info field of the file’s metadata. The field is optional and appears on files that inside of shared folders.

• read_only — If true, the content of the shared folder is readable, but can’t be modified by the user. 
• traverse_only — If true, the user only has traversal rights on the folder. Calling /files/list_folder on that folder will only return the subset of paths that the user can access.
• no_access — If true, the user may see that the folder exists, but any attempts to view its’ contents will return an error.

Deleted Content

You can modify your /files/list_folder call to include deleted content by setting include_deleted to true. The deleted content inside the folder may be available for recovery as allowed by revision history retention. You can download the deleted content by calling /files/download and specifying the revision as the path parameter. There is an example revision reference farther down in this guide.

List Folder Content Exercise:

• Go to the /files/list_folder endpoint in the API Explorer
• Select ‘Get Token’ to populate a short-lived token
• Put in a path to a Dropbox folder that you know has nested folders inside it
• Set the recursive parameter to true and click ‘Submit Call’
  • Examine the response. Where’s all the content information? It may be on the next page of results.
• Copy the cursor from your response
• Navigate to /files/list_folder/continue in the API Explorer
• Paste your cursor and click ‘Submit Call’

Congratulations! The mechanisms that you just practiced are an essential part of building world class Dropbox applications. If you find yourself struggling when trying to list folder content, try using the API Explorer to practice and tweak parameters until you find the right behavior.

When working with files using the Dropbox API, there are two special cases to be aware of: non-downloadable files and files that have been locked for editing. Both types of files may require additional logic in your app.  

Non-downloadable Files

The majority of file types in Dropbox can be downloaded. However, certain types of files are only editable in the cloud and are considered non-downloadable. That includes Google documents (Docs, Sheets, or Slides), Dropbox Paper, and Microsoft Office docs.

Non-downloadable files can be exported instead of downloaded using /files/export.

Locked Files

Files inside shared folders can be locked when a user wants to prevent unwanted edits. When you need to perform actions on a locked file, you’ll need to unlock it. However, the unlock can only be issued by either the lock holder or an admin. Both approaches are covered in the developer blog article called “File locking using the Dropbox API”.

When working with Dropbox files, there are some specific use cases that have best practices. Note that we may update this section in the future.

Content Hashing

When you need to verify that the server’s copy of a file is the same as your local version of the file, you can use the file’s content_hash, which is included in the properties of every file’s metadata.

The content_hash allows you to compare file versions without downloading them by computing your own content_hash locally. You can find step-by-step instructions on computing your own content_hash in our Content Hash Guide.

Previewing Files

Pulling large files into your app each time a user needs to preview their Dropbox content can consume a lot of bandwidth; slowing your app down and negatively impacting your user’s experience. Thankfully, the Dropbox API offers two endpoints to help retrieve content: /files/get_thumbnail and /files/get_preview.  

Need to preview an image? The /files/get_thumbnail endpoint works with most image files and provides parameters to configure the thumbnail’s file type and scaling behavior. Generating multiple thumbnails in bulk with /files/get_thumbnail_batch can further enhance your app’s performance.

Need to preview a file? The /files/get_preview endpoint generates previews of many types of files. A PDF preview is generated for most multi-page doc files (.pptx, .docx, .ai, .gslides, etc.) while HTML previews are generated for other types of files (.gsheet, .xlsx, .csv).