B2 Integration Checklist

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




Authorization and Account ID
In order 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: 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 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.

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.

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: The rest of the error codes described below can be returned from 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.

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.

Timing background work
If you are doing background work, like file synchronization, which contacts the 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 B2 service so that we can provide a higher-quality of service to all users.

Creating Buckets via the API
If your integration uses the API to create buckets on 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.