Integration Checklist

Tools that integrate with Backblaze B2 Cloud Storage and want to be featured on the Backblaze B2 integrations page need to follow the guidelines that are outlined on this page.

Click here to submit an integration.

Authorization and Account ID

To call b2_authorize_account you need an application key ID and an application key. Previously the application key ID was called account ID. This may cause some confusion, but the underlying functionality has not changed. 

However, it's important to note that when storing the Account ID properly, integrations should only store the account ID from the response given by our service. Do not store the application key ID (formerly called account ID) provided by the user. 

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 or connection reset)
• 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. 

Set a User-Agent

A User-Agent header should identify your integration and software version number for all Backblaze B2 API requests. It is also helpful to report operating system and other dependencies. The User-Agent header is part of RFC 7231. If the Backblaze operations team observes anomalous behavior with your integration, the team can identify and reach out proactively.

The common syntax is:

User-Agent: <product> / <product-version+dependencies> <comment>

For example, the User-Agent string for the 0.6.4 version of B2 CLI tool using python 2.7.9, looks like this:

User-Agent: backblaze-b2/0.6.4+python/2.7.9

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 exponential 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.
  When calling b2_authorize_account, this means that there was something wrong with the applicationKeyId or with the application key that was provided. The code unauthorized means that the application key is bad. The code unsupported means that the application key is only valid in a later version of the API.
  When uploading data using b2_upload_file or b2_upload_part, this can mean a variety of things. Try calling b2_get_upload_url or b2_get_upload_part_url again to get a new upload target and auth token. That call will either work or provide a meaningful error code.
  For all other API calls, the code returned tells you what to do. The code unauthorized means that the auth token is valid, but does not allow you to make this call with these parameters. When the code is either bad_auth_token or expired_auth_token you should call b2_authorize_account again to get a new auth token.
  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- and download-related API calls. This will cause a cap limit failure, allowing you to verify correct behavior of your code.
• 429 Too Many Requests. Backblaze 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 Backblaze B2 clients, the Backblaze 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

Backblaze 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 Backblaze B2 should handle all of these conditions in the lower levels of the code, giving developers higher level constructs for their code. 

Timing Background Work

If you are doing background work, like file synchronization, which contacts the Backblaze B2 API regularly, please select a random time during your sync period to do the background work.

For instance, if you want to synchronize once an hour, please do not just start your work during the first minute of the hour. Instead, please select a random minute of the hour (let's say the '26th' minute) and do your synchronization starting at that minute. Please select the minutes independently for each of your clients. This helps spread out the load on the Backblaze B2 service so that we can provide a higher-quality of service to all users.

Creating Buckets Using the API

If your integration uses the API to create buckets on Backblaze B2, please ensure that you create the bucket as a private bucket. If you intentionally wish to create the bucket as public, please make sure you have sufficient documentation on your application and help pages that indicate this as well as the implication of creating a public bucket. Backblaze will not certify any integration that creates public buckets without this documentation present.