Downloading

The B2 APIs are simple and straightforward, but there are still a few things that you need to look out for when writing code to download files.

Downloading Files

There are two ways to download files. b2_download_file_by_id, is used to download a file, given you have the file id, and b2_download_file_by_name using the file name. Both APIs only download one file at a time.

Applications intending to use the RANGE header to multithread the download of files can use the more efficient HEAD request to fetch file information, as opposed to making an initial call to download a single byte.

Some buckets may be private and require you to have an authorization token to access files, see b2_authorize_account. Alternatively, you can use b2_get_download_authorization as an authorization token to access files with a specific filename prefix.

Errors returned from b2_download_file_by_id and b2_download_file_by_name are usually because of a bad request, or because the request is unauthorized. Another cause of these errors is that the file was previously deleted and so can no longer be found.

  • 400 Bad Request
    • bad_request - message will describe the problem
  • 401 Unauthorized
    • missing_auth_token - there is no Authorization header
    • bad_auth_token - the authorization token is not valid
    • expired_auth_token - the authorization token had expired
    • unauthorized - the auth token used does not allow access to this file
  • 404 Not Found
    • not_found - the bucket or file does not exist
  • 416 Range Not Satisfiable
    • range_not_satisfiable - the request is outside the size of the file content
  • 429 Too Many Requests
    • too_many_requests - your account has too many concurrent downloads
  • 5xx
      There is a problem in the service. Retry with exponential back-off.

Downloading in Parallel

The URL and authorization token that you get from b2_authorize_account can be used by multiple downloading threads. You can download in parallel to increase overall throughput.

Cache-Control Policies

B2 allows you to configure Cache-Control policies on a bucket level. During the creation of a bucket or when updating a bucket, you can configure the policy by setting the Cache-Control in the Bucket Info. For general information about Bucket Info, see Buckets

When setting the policy the key must be Cache-Control, which is case-sensitive, and the value must be max-age=number, which specifies the number of seconds to cache the file.

Below is a java example of b2_create_bucket, where we set the cache policy for the bucket.

import java.io.*;
import java.util.*;
import java.net.HttpURLConnection;
import java.net.URL;

String apiUrl = ""; // Provided by b2_authorize_account
String accountId = ""; // Obtained from your B2 account page.
String accountAuthorizationToken = "";  // Provided by b2_authorize_account
HttpURLConnection connection = null;

try {
    URL url = new URL(apiUrl + "/b2api/v2/b2_create_bucket");
    connection = (HttpURLConnection)url.openConnection();
    connection.setRequestMethod("POST");
    connection.setRequestProperty("Authorization", accountAuthorizationToken);
    connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
    connection.setRequestProperty("charset", "utf-8");
    connection.setRequestProperty("Content-Length", Integer.toString(postData.length));
    connection.setDoOutput(true);
    DataOutputStream writer = new DataOutputStream(connection.getOutputStream());
    writer.write(
    "{" +
        "\"accountId\":\"" + accountId + "\"," +
        "\"bucketName\":\"photos\",
        \"bucketType\":\"allPrivate\",
        \"bucketInfo\": {\"Cache-Control\":\"max-age=600\"}"
    + "}"
        .getBytes(StandardCharsets.UTF_8));
} catch (Exception e) {
    e.printStackTrace();
} finally {
    connection.disconnect();
}

Upon downloading a file, the response headers will contain the policy set by the bucket. If the bucket has no policy set, the default is Cache-Control : max-age=0, no-cache, no-store. If the bucket has a setting, that will be used instead.