Calling the API
Most of the API calls for B2 Cloud Storage accept a POST with JSON data, and return JSON data. The code samples for each of the calls show how to do that in a variety of languages.
Constructing the URL
For most calls, you construct the URL by combining four things:
- The
apiUrl
returned by b2_authorize_account /b2api
/v
versionNumber/
apiName
The version number says which version of the API you want to call. (See API Versions for more details.) The API name says which API entry point you want to call. The resulting URL will look like this if you are calling version 2, the current version, of b2_list_file_names:
https://api123.backblazeb2.com/b2api/v2/b2_list_file_names
Authorizing an Account
The call to b2_authorize_account is special because
the API URL is fixed: https://api.backblazeb2.com
, so the full URL will
look like this:
https://api.backblazeb2.com/b2api/v2/b2_authorize_account
Uploading Files
When uploading files, just use the exact URL returned from b2_get_upload_url or b2_get_upload_part_url. The version number in that URL will match the version number of the call that returned it. The headers of the upload request hold the parameters, and the body holds the file being uploaded.
The URL to upload a file looks like this:
https://pod-000-1013-02.backblaze.com/b2api/v2/b2_upload_file/8f433564b42f9c515e21021e/c001_v0001013_t0020
Downloading Files by ID
Requests to b2_download_file_by_id follow the normal pattern, but use the downloadUrl instead of the apiUrl returned by b2_authorize_account.
The URL to download a file by ID looks like this:
https://f123.backblazeb2.com/b2api/v2/b2_download_file_by_id
Downloading Files by Name
The URL to download a file by name is made of three parts:
- The
downloadUrl
returned by b2_authorize_account /
bucketName/
fileName
The download URL will look like this:
https://f123.backblazeb2.com/file/my-bucket/myFile.txt
Status Code Returned
For all calls to B2, the HTTP status code returned indicates success or failure. Unsuccessful calls return a JSON error structure in the body of the response that includes the status, a "code" that is a short string, and a "message" intended only for humans.
A status of 200 (OK) means success, and 206 (Partial Content) means success
when downloading using the Range
header. Any code in the 400
or 500 range is a failure. See the section below on Error Handling
for details. At present, B2 does not use redirects (status codes
in the 300 range).
POST JSON -> JSON
This is the normal case for API calls to B2. You create a request as a JSON object, POST it to the B2 service, and get a JSON object in the response.
This is a simple example using curl
on the command-line:
ACCOUNT_ID=... # Comes from your account page on the Backblaze web site ACCOUNT_AUTH_TOKEN=... # Comes from the b2_authorize_account call API_URL=... # Comes from the b2_authorize_account call BUCKET_NAME=any_name_you_pick # 63 char max: letters, digits, and hyphen - BUCKET_TYPE=allPrivate # Either allPublic or allPrivate curl -H "Authorization: $ACCOUNT_AUTH_TOKEN" \ -d "{\"accountId\": \"$ACCOUNT_ID\", \"bucketName\": \"$BUCKET_NAME\", \"bucketType\": \"$BUCKET_TYPE\"}" \ "$API_URL/b2api/v2/b2_create_bucket"
Will return this:
{ "bucketId" : "e1256f0973908bfc71ed0c1z", "accountId" : "12f634bf3cbz", "bucketName" : "any_name_you_pick", "bucketType" : "allPrivate" }
GET -> JSON
All API calls that accept POST-ed JSON also accept the parameters as URL query parameters. This is much more convenient for ad-hoc requests that you type by hand, and for using in a browser.
This request is equivalent to the one above:
ACCOUNT_ID=... # Application Key from the Backblaze web site ACCOUNT_AUTH_TOKEN=... # Comes from the b2_authorize_account call API_URL=... # Comes from the b2_authorize_account call BUCKET_NAME=any_name_you_pick # 63 char max: letters, digits, and hyphen - BUCKET_TYPE=allPrivate # Either allPublic or allPrivate curl -H "Authorization: $ACCOUNT_AUTH_TOKEN" \ "$API_URL/b2api/v2/b2_create_bucket?accountId=$ACCOUNT_ID&bucketName=$BUCKET_NAME&bucketType=$BUCKET_TYPE"
Uploading Files
When you upload a file, the body of the POST is the file being uploaded, and the other information is passed in the HTTP headers. First call b2_get_upload_url to retrieve specific data to pass in.
ACCOUNT_ID=... # Application Key from the Backblaze web site ACCOUNT_AUTH_TOKEN=... # Comes from the b2_authorize_account call BUCKET_ID=... # ID for the bucket to upload to API_URL=... # Comes from the b2_authorize_account call curl \ -H "Authorization: $ACCOUNT_AUTH_TOKEN" \ -d "{\"bucketId\": \"$BUCKET_ID\"}" \ "$API_URL/b2api/v2/b2_get_upload_url"
This will return the following response, including the upload authorizationToken and the uploadUrl to use.
{ "authorizationToken": "4_0028bc628f87f040000000001_019e8f5e_263f9e_upld_Yr3aQphj7BktivNK60zSnoh6UDU=", "bucketId": "e1256f0973908bfc71ed0c1z", "uploadUrl": "https://pod-000-1143-18.backblaze.com/b2api/v2/b2_upload_file/e1256f0973908bfc71ed0c1z/c002_v0001143_t0002" }
Upload call can now be completed as follows:
FILE_TO_UPLOAD=~/Downloads/logo.jpeg # Name and URL of the file to upload MIME_TYPE=b2/x-auto # Mime type of the file. X-auto can also be leveraged. SHA1_OF_FILE=$(openssl dgst -sha1 $FILE_TO_UPLOAD | awk '{print $2;}') # SHA1 of the file UPLOAD_URL=... # From the b2_get_upload_url call UPLOAD_AUTHORIZATION_TOKEN=... # From the b2_get_upload_url call curl \ -H "Authorization: $UPLOAD_AUTHORIZATION_TOKEN" \ -H "X-Bz-File-Name: $FILE_TO_UPLOAD" \ -H "Content-Type: $MIME_TYPE" \ -H "X-Bz-Content-Sha1: $SHA1_OF_FILE" \ -H "X-Bz-Info-Author: unknown" \ --data-binary "@$FILE_TO_UPLOAD" \ $UPLOAD_URL
This will return a JSON response containing the File ID of the new file:
{ "fileId" : "4_he1256f0973908bfc71ed0c1z_f000000000000472a_d20140104_m032022_c001_v0000123_t0104", "fileName" : "typing_test.txt", "accountId" : "12f634bf3cbz", "bucketId" : "e1256f0973908bfc71ed0c1z", "contentLength" : 46, "contentSha1" : "bae5ed658ab3546aee12f23f36392f35dba1ebdd", "contentType" : "text/plain", "fileInfo" : { "author" : "unknown" } }
Downloading Files
To download a file by name, you simply GET a path built from the
download URL that b2_authorize_account
returned, /file/
, the name of the bucket, and the name
of the file, such as:
curl https://f001.backblazeb2.com/file/photos/cats/kitten.jpg
The file will be returned, and the information about the file, including its SHA1 and MIME type is in the HTTP headers.
Error Handling
Failures to connect to the B2 servers, and networking problems in general can cause errors, which are reported in the normal way.
If you get a response from B2, the HTTP status code will tell you whether it is an error or not. A status of 200 (OK) means that the call was successful. For most calls, a successful response contains the JSON that is described in the API documentation. Any code other than 200 is an error, and the response will contain a JSON error structure indicating what went wrong. The documentation for each API includes information on specific errors return for that API; the general classes of errors are:
HTTP Status Code
200
The request was successful, and the response contains the JSON structure described in the page for the call.
400
BAD REQUEST -
There is a problem with a passed in request parameters -
the JSON error structure returned will contain an
error code of bad_request
and a human-readable
error message describing the problem.
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.
403
FORBIDDEN - You have a reached a storage cap limit, or account access may be impacted in some other way; see the human-readable message.
408
REQUEST TIMEOUT - The service timed out trying to read your request.
429
TOO MANY REQUESTS - B2 may limit API requests on a per-account basis.
500
INTERNAL ERROR - An unexpected error has occurred.
503
SERVICE UNAVAILABLE - The service is temporarily unavailable. The human-readable message identifies the nature of the issue, in general we recommend retrying with an exponential backoff between retries in response to this error.
JSON Error Structure
status
The numeric HTTP status code. Always matches the status in the HTTP response.
code
A single-identifier code that identifies the error.
message
A human-readable message, in English, saying what went wrong.
Example:
{ "status" : 400, "code" : "invalid_bucket_name", "message" : "bucket name is too long" }