Delete, Download, and Search Files

Learn how to delete, download and search files using the Dropbox API.

We'll cover the following

In this lesson, we’ll look at three important endpoints that will help us delete, download, and search files from Dropbox. These endpoint operations are the following:

  • delete
  • download
  • search_v2

Delete a file or a folder

The files/delete_v2 endpoint deletes a file or a folder from a specified location. If we provide a path to a folder, then all of its content will also be deleted. It requires us to enable the permission files.content.write to perform this action.

Let’s delete the DestFolder that we created with the copy_v2 endpoint.

Request parameters

Let’s take a look at the request parameters, descriptions, and formats in the table below.

Parameter Name

Format

Required

Description

path

id

String

Unique ID of folder or file that is deleted.

parent_rev

String

No

Only applicable to files. A file will only be deleted if the current revisions match the file's most recent revisions.

Press + to interact
// Define import libraries here
import fetch from 'node-fetch';
// Define API key here
const token = '{{TOKEN}}'
// Define endpoint URL here
const endpointUrl = new URL('https://api.dropboxapi.com/2/files/delete_v2');
// Define Header Parameters here
const headerParameters = {
  'Authorization': `Bearer ${token}`,
  'Content-Type': 'application/json',
};
// Define Body Parameters here
const bodyParameters = JSON.stringify({
  path: "/home/DestFolder"
});
// Set the API call options
const options = {
  method: 'POST',
  headers: headerParameters,
  body: bodyParameters,
};
// Function to make the API call
async function deleteFiles() {
  try {
    const response = await fetch(endpointUrl, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
// Call function to make the API call
deleteFiles();

In the code above, we see the following:

  • Line 2: We import the fetch library that we need to use in our code from node-fetch.
  • Line 5: We get the value for TOKEN to use for authentication.
  • Line 8: We define the request URL.
  • Lines 11–14: We define the headers of the fetch request. It includes the authorization and the type of content, which is application/json in most cases.
  • Lines 17–19: We define the bodyParameters of the fetch request.
  • Lines 22–26: We set the API call options.
  • Lines 29–39: We create a function to make the API call. It will try to get the response and will pass the response to the custom function printResponse; otherwise, it will catch the error and will pass it to the custom function printError.
  • Line 42: We call the function deleteFiles to make the API call.

Response fields

Our call’s response will provide the metadata of the deleted folder, which includes the name, path_display, id, and so on.

Response field

Format

Description

name

String

Name of the folder or file that is deleted.

path_display

String

Case-insensitive path to the folder or file that is deleted.

id

String

Unique ID of folder or file that is deleted.

Download a file

In this section, we’ll see how to download a file using the /files/download endpoint for the files namespace. We need to enable the files.content.read permission to call this endpoint.

Request parameters

This endpoint takes only one required parameter, the path of the file we want to download. We can specify a path in multiple ways:

  • With a descriptive name of the folder or file.
  • Using the id of the file as the path.
  • Using the latest rev of the file.

Any of these methods can work, but we’ll use the first one.

Press + to interact
// Define import libraries here
import fetch from 'node-fetch';
// Define API key here
const token = '{{TOKEN}}'
// Define endpoint URL here
const endpointUrl = new URL('https://content.dropboxapi.com/2/files/download');
// Define Header Parameters here
const headerParameters = {
  'Authorization': `Bearer ${token}`,
  'Dropbox-API-Arg': "{\"path\":\"/home/TestFolder/demo.png\"}",
};
// Set the API call options
const options = {
  method: 'POST',
  headers: headerParameters,
};
// Function to make the API call
async function downloadFile() {
  try {
    const response = await fetch(endpointUrl, options);
    // Custom function for printing the API response
    console.log('status code: ', response.status);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
// Call function to make the API call
downloadFile();

In the code above, we do the following:

  • Line 2: We import the fetch library that we need to use in our code from node-fetch.
  • Line 5: We get the value for TOKEN to use for authentication.
  • Line 8: We define the request URL.
  • Lines 11–14: We define the headers of the fetch request. It includes the authorization and the type of content, which is application/json in most cases.
  • Lines 17–20: We set the API call options.
  • Lines 23–33: We create a function to make the API call. It will try to get the response and will pass the response to the custom function printResponse; otherwise, it will catch the error and will pass it to the custom function printError.
  • Line 36: We call the function downloadFile to make the API call.

Response

We won’t be able to download the file when we click the “Run” button because of Educative’s platform restrictions. But don’t worry! The returned status code of 200 shows that our request was successful.

Search for files and folders

The /files/search_v2 endpoint is used to make search queries for files and folders in the user’s Dropbox. It requires us to enable the files.metadata.read permission so that we can perform this operation.

Request parameters

Let’s see what parameters we can pass to this endpoint.

  • A query is a required parameter that takes what we want to search for as a string.
  • The options parameter is an optional parameter that’s used to be more targeted in search operations. It consists of the following parameters:

Parameter Name

Format

Required

Description

path

String

Optional

Used to provide a specific location to search for our query.

max_results

Integer

Optional

Specifies the number of results.

order_by

String

Optional

Specifies the order of output.

file_status

String

Optional

Specifies that our search will include deleted files or only active files.

filename_only

Boolean

Optional

Restricts our search to file names only.

file_extensions

String

Optional

Restricts our search to a specific file extension only.

file_categories

String

Optional

Specifies file categories like pdf, png, etc.

Let’s search for a file using the search_v2 endpoint.

Press + to interact
// Define import libraries here
import fetch from 'node-fetch';
// Define API key here
const token = '{{TOKEN}}'
// Define endpoint URL here
const endpointUrl = new URL('https://api.dropboxapi.com/2/files/search_v2');
// Define Header Parameters here
const headerParameters = {
  'Authorization': `Bearer ${token}`,
  'Content-Type': 'application/json',
};
// Define Body Parameters here
const bodyParameters = JSON.stringify({
  query: "demo",
  options: {
        path:"/home/TestFolder",
        // max_results: 1,
        // file_status: "active",
        // file_categories:[{".tag":"image"}]
        }
});
// Set the API call options
const options = {
  method: 'POST',
  headers: headerParameters,
  body: bodyParameters,
};
// Function to make the API call
async function searchFiles() {
  try {
    const response = await fetch(endpointUrl, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
// Call function to make the API call
searchFiles();

In the code above, we do the following:

  • Line 2: We import the fetch library that we need to use in our code from node-fetch.
  • Line 5: We get the value for TOKEN to use for authentication.
  • Line 8: We define the request URL.
  • Lines 11–14: We define the headers of the fetch request. It includes the authorization and the type of content, which is application/json in most cases.
  • Lines 17–25: We define the bodyParameters of the fetch request.
  • Lines 28–32: We set the API call options.
  • Lines 34–44: We create a function to make the API call. It will try to get the response and will pass the response to the custom function printResponse; otherwise, it will catch the error and will pass it to the custom function printError.
  • Line 47: We call the function searchFiles to make the API call.

Note: In order to experience the behavior of this endpoint more clearly, try to add more files that have the same name but different extensions.

Response

In response to the code above, we’ll get all the instances for our query. We’ll get all the metadata of the files and folders found in the specified location.