API Versions
Over time, the Backblaze B2 APIs get updated to support new features, and to make them easier to use. When changes are not compatible, we make a new version of the API, and keep supporting the old versions.
Specifying an API Version
When you call an API, you include the API version number in the URL
of the call. The path for an API call starts with something like
/b2api/v2/
. The "v2" is the version number.
The current version number is v2
.
In general, you should always used the latest version number. And you should update your client code periodically to take advantage of the latest version. The latest version will have the latest performance improvements, and may be the only place to get the latest features. In general, our goal is that upgrading from one version to the next will be straightforward.
Support for Old Versions
Backblaze does not have any plans to stop supporting old versions. If we ever do make such plans, we will announce them at least a year in advance, to give you plenty of time to update your code.
Compatibility
Over time, the B2 APIs will grow to support new features. As they grow, the APIs will change.
The URLs for the APIs include a version number ("v2") in the path. This remains the same as long as the API stays compatible. When we have to make an incompatible change, the new version of the API gets a new version number ("v2"), and the old API will continue to be supported for a while.
When a new version of the APIs is created, usually only a few of the calls
actually change. The new version number is used to get the new version
of those calls, and can also be used for all of the other calls.
For example, if v37
is released with an incompatible change to b2_create_key, you'll
need to use v37
to access the new features. You can also use
v37
with all other API calls, and they will behave just as they
did in v36
.
Some API changes are compatible, and don't require a version change. These can happen at any time, and your code should be able to deal with them:
- Adding new API entry points.
- Allowing a wider range of values in an input field. For example, allowing a bigger number in maxFileCount in b2_list_file_names.
- Adding a new optional field in a request, where leaving out the field keeps the old behavior.
- Adding a new field in a response. Your code should ignore any fields it doesn't expect.
- Allowing a call that was not allowed before.
These are incompatible changes, and won't happen without going to a new API version number:
- Changing the behavior of an existing call with existing parameters.
- Disallowing previously allowed values. For example, shortening the maximum length of a bucket name.
- Adding new required fields in a request.
- Removing a field from a request.
- Removing a field from a response.
-
Returning a wider set of values in a response, unless the documentation
explicitly says that it could happen.
Note that
bucketType
for buckets, andaction
for file versions both say that they may be extended in the future.
Version History
The current version is v2
.
The documentation pages for each API call describe v2
, with the
differences between v1
and v2
in the "API Versions"
section of the page.
The list of versions below describes the changes in each version.
v2: Object Lock (May 11, 2021)
To allow B2 clients to view Object Lock information, some API calls return more fields:
-
b2_list_file_names now returns
fileRetention
,legalHold
. -
b2_list_file_versions now returns
fileRetention
,legalHold
.
v2: Server-Side Encryption (March 5, 2021)
To allow B2 clients to view Server-Side Encryption information, some API calls return more fields:
-
b2_list_file_names now returns
serverSideEncryption
. -
b2_list_file_versions now returns
serverSideEncryption
.
v2: Remove application key workaround (Sept 13, 2018)
Version v2
cleans up the workaround introduced in the
August 9, 2018 release. It goes back to returning exactly what
you ask for in a query, and no longer has implicit filters implied
by the application key being used. It's easier to explain, and
easier to know what to expect in response to a query, if the results
of the query do not depend on the application key you happened to use.
See Application Keys for information on how to work with application keys that have bucket and file name restrictions.
To make it easier to work with application keys with restricted access:
-
When the application key is restricted to a bucket, the response from
b2_authorize_account now
includes the
bucketName
, in addition to thebucketId
that was already there.
To simplify B2 clients, all API calls that return information about files now return the same structure. This means that some calls return more fields:
-
b2_hide_file now returns
accountId
,bucketId
. -
b2_list_file_names now returns
accountId
,bucketId
. -
b2_list_file_versions now returns
accountId
,bucketId
. -
b2_list_unfinished_large_files now returns
action
(always "upload"),contentLength
(always null), andcontentSha1
(always null). -
b2_start_large_file now returns
action
(always "upload"),contentLength
(always null), andcontentSha1
(always null).
And because making a new API version is a good time to drop deprecated fields, these fields are not present when you use v2:
-
The response from b2_authorize_account
no longer contains
minimumPartSize
. UserecommendedPartSize
andabsoluteMinimumPartSize
instead. -
The responses from
b2_list_file_names,
b2_list_file_versions, and
b2_hide_file, no longer contain
size
. UsecontentLength
instead.
v1: Workaround for existing applications and application keys (August 9, 2018)
Because some existing integrations were having trouble with
the incompatibility in the July 26 release,
we broke our own rules and changed the behavior of
some calls to help existing software support the new
Application Keys feature.
The updated v1 as of this release implicitly restricts
b2_list_buckets
,
b2_list_file_names
,
b2_list_file_versions
, and
b2_list_unfinished_large_files
to things that are allowed by the application key. When you ask for all buckets,
or for files in a bucket, the query is automatically restricted to the
things that your application key is allowed access to.
v1: Application keys (July 26, 2018)
New calls to manage application keys: b2_create_key, b2_list_keys, b2_delete_key, and b2_create_key.
New optional bucketName
and bucketId
parameters
to b2_list_buckets provide a way to get
information about just one bucket. This is useful when using an application
key that allows access to only one bucket.
New optional namePrefix
parameter to
b2_list_unfinished_large_files
so that you can restricted the results to just some
files. This is especially useful with application
keys that have file name restrictions.
New field allowed
in response from
b2_authorize_account , which includes
information about what the application key allows you to do, and restrictions
it has on bucket and file name prefix.
This release was incompatible with previous releases because it broke an (unwritten) rule that once you authenticate, all of the calls will be authorized. If you authenticate with an application key that has restricted capabilities, is restricted to a bucket, or is restricted to a file name prefix, some calls will return a 401 Unauthorized.
We didn't anticipate the quick uptake of users making these keys and using them in existing integrations which, very reasonably, weren't prepared for the restrictions, which is the reason for the workaround released on August 9.
v1: Original release (September 22, 2015)
Version 1 of the APIs launched when the B2 Storage service launched.