question about response from download method

[Barry L.12]

Hello,

I'm studying the documentation for the files /download method in both the API Explorer:

https://dropbox.github.io/dropbox-api-v2-explorer/#files_download

And in the developer documentation area:

https://www.dropbox.com/developers/documentation/http/documentation#files-download

In both cases/places the documentation indicates that a data structure is returned, showing the meta-data of the item to be downloaded. But where is it documented where and how the actual data of the item -- the file contents -- is obtained?

Meanwhile, in my test program, I'm finding that the "return value" of the call to /download is, in fact, the file contents, and if I write that data to a file in the local file system, I get a valid file (in this case a jpg photo that's viewable in any app that displays image data). But where, then, do I obtain the meta-data about the photo that the documentation says is returned?

Thanks,

Barry

[Steve M.]

Take a look at the "Request and response formats" section at https://www.dropbox.com/developers/documentation/http/documentation.

In particular:

Content-download endpoints

As with content-upload endpoints, arguments are passed in the Dropbox-API-Arg request header or arg URL parameter. The response body contains file content, so the result will appear as JSON in the Dropbox-API-Result response header. These endpoints are also on thecontent.dropboxapi.com domain.

These endpoints also support HTTP GET along with ETag-based caching (If-None-Match) and HTTP range requests.

[Barry L.12]

I really appreciate the response. Unfortunately, I don't understand it.

The origin of the problem is that Dropbox has dropped support for PHP. I had this all working in API v1. In order to use API v2 I've "rolled my own". If you're willing to look at some code, here is my simple PHP function to retrieve a file:

function dbx_get_file($token, $in_filepath, $out_filepath)
  {
  $out_fp = fopen($out_filepath, 'w+');
  if ($out_fp === FALSE)
     {
     echo "fopen error; can't open $out_filepath\n";
     return (NULL);
     }

  $url = 'https://content.dropboxapi.com/2/files/download';
 
  $header_array = array(
     'Authorization: Bearer ' . $token,
     'Content-Type:',
     'Dropbox-API-Arg: {"path":"' . $in_filepath . '"}'
     );

  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, TRUE);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $header_array);
  curl_setopt($ch, CURLOPT_FILE, $out_fp);

  $output_array = array();
  $output = curl_exec($ch);

  if ($output === FALSE)
     {
     echo "curl error: " . curl_error($ch);
     }

  else
     {
     $output_array = json_decode($output, TRUE);
     }

  curl_close($ch);
  fclose($out_fp);

  return($output_array);
  }  // dbx_get_file()

As I said, this function returns the contents of the requested file. Where, then, is the meta-data?

Thanks, and sorry if I'm missing something obvious.

Barry

[Steve M.]

The metadata is in the Dropbox-API-Result header of the response.

[Barry L.12]

Ok, sorry I'm being dense. Given the code I posted, how do I retrieve the Dropbox-API-Result header?

[Steve M.]

You're not being dense... this is extremely hard to do with curl in PHP. Here's some working code:

function dbx_get_file($token, $in_filepath, $out_filepath)
    {
    $out_fp = fopen($out_filepath, 'w+');
    if ($out_fp === FALSE)
        {
        echo "fopen error; can't open $out_filepath\n";
        return (NULL);
        }

    $url = 'https://content.dropboxapi.com/2/files/download';

    $header_array = array(
        'Authorization: Bearer ' . $token,
        'Content-Type:',
        'Dropbox-API-Arg: {"path":"' . $in_filepath . '"}'
    );

    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, TRUE);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $header_array);
    curl_setopt($ch, CURLOPT_FILE, $out_fp);

    $metadata = null;
    curl_setopt($ch, CURLOPT_HEADERFUNCTION, function ($ch, $header) use (&$metadata)
        {
        $prefix = 'dropbox-api-result:';
        if (strtolower(substr($header, 0, strlen($prefix))) === $prefix)
            {
            $metadata = json_decode(substr($header, strlen($prefix)), true);
            }
        return strlen($header);
        }
    );

    $output = curl_exec($ch);

    if ($output === FALSE)
        {
        echo "curl error: " . curl_error($ch);
        }

    curl_close($ch);
    fclose($out_fp);

    return($metadata);
    } // dbx_get_file()

$metadata = dbx_get_file("<REDACTED>", '/test.txt', 'test.txt');
echo "File " . $metadata['name'] . " has the rev " . $metadata['rev'] . ".\n";

[Steve M.]

Compare to the much saner Requests library:

$response = Requests::post("https://content.dropboxapi.com/2/files/download", array(
    'Authorization' => "Bearer $token",
    'Dropbox-Api-Arg' => json_encode(array('path' => '/test.txt')),
));

$fileContent = $response->body;
$metadata = json_decode($response->headers['Dropbox-Api-Result'], true);

echo "File " . $metadata["name"] . " has the rev " . $metadata["rev"] . ".\n";

[Barry L.12]

Wow, thanks! You, sir, are a star. This is the first I've heard of the Requests library. You can bet I'll be spending some time studying it.
It's interesting to note that both of the Dropbox API v2 PHP libraries provided by community developers are based on curl, and both are insanely complex. I wonder if they could be improved by using the Requests library...
Anyway, thanks again.

[Daniel S.33]

Just in case any other Perl users come across this here is how to get it in Perl (using LWP::UserAgent, HTTP::Request, HTTP::Headers and JSON😞

my $response = $ua->request($request); 
my $file_contents = $response->content;
my $json = decode_json($response->header("Dropbox-Api-Result"));
my $filename = $json->{name};