B2 Integration Checklist

Tools that integrate with B2 and want to be featured on the B2 integrations page need to follow these guidelines:

Uploading files
During an upload using the b2_upload_file or b2_upload_part API, if one of the following conditions occur, the developer should call b2_get_upload_url or b2_get_upload_part_url and re-attempt the upload using the new URL and auth key pair:
  • If an HTTPS connection cannot be made. (e.g., connection timeout).
  • The HTTPS connection is broken. (e.g., broken pipe.)
  • The HTTPS connection times out waiting for a response (socket timeout).
  • The HTTP response status is 408 (Request Timeout).
  • The HTTP response status is between 500-599, including 503 Service Unavailable.
To test your code, add a X-Bz-Test-Mode: fail_some_uploads header to the b2_upload_file API call. This will cause intermittent artificial failures, allowing you to test the resiliency of your code.

Developers do not need to call b2_get_upload_url or b2_get_upload_part_url for each file (or part) they wish to upload. You can upload multiple files (or parts) in serial using a single URL/auth token pair until one of the above conditions occurs.

Detailed information and pseudo-code examples can be found in the Uploading section of the B2 API documentation.

Multithreading uploads
If your tool is uploading many files, the best performance will be achieved by multithreading the upload and launching multiple threads simultaneously.
  • When initializing upload threads, call b2_get_upload_url or b2_get_upload_part_url for each thread. The returned upload URL / upload authorization token should be used in this thread to upload files until one of the error conditions described above occurs. When that happens, simply call b2_get_upload_url or b2_get_upload_part_url again and resume the uploads.
  • When uploading files larger than 200MB, use the large files support to break up the files into parts and upload the parts in parallel.

Multithreading downloads
Downloads over 200MB should be split into parts and downloaded simultaneously. Once all parts are downloaded, the large file should be stitched together.
  • Use the Range header on b2_download_file_by_id or b2_download_file_by_name to download individual parts of a file.

Handling error response status codes
See the Calling the API page section on Error Handling for a general description of error code classes. Some specific things to check in your integration are:
  • 503 errors from any API except b2_upload_file or b2_upload_part. (Handling a 5xx error on an upload API is described in the Uploading Files section above.) When this error occurs, it may include a "Retry-After" header where the value is the number of seconds a developer should wait before re-issuing the command. If the header is not present, the developer should retry using an expotential backoff starting with 1 second. These status codes may be returned from any B2 API.
The rest of the error codes described below can be returned from any B2 API.
  • 401 Unauthorized. Returned while uploading, indicates the upload URL has expired; A new upload URL can be obtained from b2_get_upload_url or b2_get_upload_part_url. Returned from b2_authorize_account, indicates the account ID is wrong, the account does not have B2 enabled, or the application key is not valid. For all other APIs, a 401 indicates the Authorization token, originally returned from b2_authorize_account is no longer valid. If your process or application is long running, you should cache the B2 application id and key. When this error occurs, simply fetch a new authorization token and retry the previous command. To test your code, add a X-Bz-Test-Mode: expire_some_account_authorization_tokens header. This will cause account authorization tokens to expire frequently, allowing you to verify that your code correctly re-establishes authorization.
  • 403 Forbidden, cap_exceeded or account in bad standing. Quit immediately and inform the user they need to log in and review their B2 Caps. To test your code, add a X-Bz-Test-Mode: force_cap_exceeded header before making upload-related API calls. This will cause a cap limit failure, allowing you to verify correct behavior of your code.
  • 429 Too Many Requests. B2 may limit API requests on a per-account basis. When the 429 status code is returned from an API, the response will also include a "Retry-After" header where the value is the number of seconds a developer should wait before re-issuing the command. This status code may be returned on any B2 API.

Managing metadata for interoperability
Setting consistent and appropriate metadata when uploading files will allow for different B2 clients, the B2 web user interface and the B2 Command Line Tool to interoperate correctly. Metadata is set as an HTTP request header when uploading files. Metadata in B2 is immutable.
  • X-Bz-Info-src_last_modified_millis - If the original source of the file being uploaded has a last modified time concept, Backblaze recommends using this header. The value should be a base 10 number which represents a UTC time when the original source file was last modified. It is a base 10 number of milliseconds since midnight, January 1, 1970 UTC. This fits in a 64 bit integer such as the type "long" in the programming language Java. It is intended to be compatible with Java's time long. For example, it can be passed directly into the Java call Date.setTime(long time). This metadata value should be set for files being uploaded using b2_upload_file or b2_start_large_file when using the Large Files multi-part upload APIs.
  • X-Bz-Info-large_file_sha1 - When using the Large Files multi-part upload API, the SHA1 of the entire large file is not required. If the caller knows the SHA1 of the entire large file being uploaded, Backblaze recommends setting this metadata value. This is only relevant for uploads using the b2_start_large_file API. Single file uploads using b2_upload_file require a SHA1.

Deleting file versions
B2 automatically creates versions of files uploaded to the same bucket, with the same name.

If your application allows a user to delete a file and there are multiple versions of that file, it's probably best to ask the user if they want to delete the last version or all versions.

Note: Language libraries and API wrappers for B2 should handle all of these conditions in the lower levels of the code, giving developers higher level constructs for their code.