Contents x
S3-Compatible API
    • Print
    • Dark
      Light
    Contents

    S3-Compatible API

      • Print
      • Dark
        Light
      Article summary

      The Backblaze B2 Cloud Storage S3-Compatible API does the same thing as the Native API—it allows you to interact with Backblaze B2—but it follows the S3 syntax. With the S3-Compatible API, if your application is already written to use the S3 API, Backblaze B2 will just work, with minimal code changes on your end. The S3-Compatible API provides developers with the following benefits:

      • You do not have to learn a new API.
      • You can use your existing tools that are written to the S3 API.
      • Performance will be just as good, and you’ll get all the benefits of Backblaze B2.

      For all of the Backblaze API operations and their corresponding documentation, see API Documentation.

      Naming Restrictions

      The S3-Compatible API features slightly different restrictions on file and bucket names than the AWS S3 API. Refer to the Buckets and Files page for naming restrictions.

      Access Control Lists

      The S3-Compatible API features limited support for access control lists (ACLs). Get Object ACL and Get Bucket ACL calls will work as expected. However, object-level ACLs are not supported. For example, a Get Object ACL call returns the ACL for the bucket in which the object is contained.

      If a bucket is private, the ACL that is returned for the bucket and any files within the bucket are “private.” If a bucket is public, the ACL that is returned for the bucket and any files within the bucket are “public-read.”

      The S3-Compatible API supports the Put Bucket ACL call to change between "private" and “public-read” only. Attempting to put a different value returns an error.

      The call succeeds only when the specified ACL matches the ACL of the bucket.

      Pre-Signed URLs

      The S3-Compatible API supports pre-signed URLs for downloading and uploading. You can generate pre-signed URLs using the AWS CLI, AWS Tools for PowerShell, s3cmd, and AWS SDKs.

      The following guides can help you configure these tools:

      Server-Side Encryption

      The S3-Compatible API supports server-side encryption of data before storing using either Backblaze-managed keys (SSE-B2) or using customer-managed keys (SSE-C). For more information on supported SSE options, click here.

      Get Object Tagging

      The S3-Compatible API does not fully support object tagging. Therefore, the implementation of Get Object Tagging returns a set of empty tags. This implementation is provided for compatibility with certain integrations.

      Copy Object and Tagging

      The S3-Compatible API does not fully support object tagging. The x-amz-tagging-directive header is allowed on the Copy Object API, but it will be ignored, no matter the value that you supply. Also, note that the x-amz-tagging header will be explicitly rejected if it is included on the Copy Object (or Put Object) API calls. This implementation is provided for compatibility with certain integrations.

      Unsupported Features

      The S3-Compatible API does not currently support the following features:

      • ACLs
      • IAM Roles
      • Object Tagging
      • Bucket Logging
      • Website Configuration
      • Lifecycle Rules (This feature is supported by the Backblaze B2 Native API.)
      • Browser-based uploads to pre-signed URLs using POST
      • Requests that include the following checksum HTTP headers are rejected with a 400 Bad Requestresponse:
        • x-amz-checksum-crc32
        • x-amz-checksum-crc32c
        • x-amz-checksum-sha1
        • x-amz-checksum-sha256
        • x-amz-checksum-algorithm
        • x-amz-checksum-mode

      IPv6 Support

      Starting mid-September this year, the S3-Compatible API will support IPv6 in the US-West region. Additional regions are scheduled for rollout of IPv6 support soon after.

      No changes to your code should be required to use IPv6 addresses with Backblaze B2 Cloud Storage and the S3-Compatible API.

      What is IPv6?

      IPv6 is a version of the Internet Protocol that uses a larger address space than IPv4, its predecessor and currently the most common format for IP addresses.

      IPv6 addresses consist of eight groups of four hexadecimal digits with each group separated by a colon. For example:

      2001:db8:1f70:999:de8:7648:3a49:6e8

      In comparison, IPv4 notation consists of four groups of decimal digits with the groups separated by dots. For example:

      198.51.100.1

      Can I still use IPv4 addresses?

      Yes. The S3-Compatible API will continue to support IPv4 addresses for the foreseeable future.

      Will using IPv6 incur additional costs?

      No.

      Is IPv6 more secure than IPv4?

      Requests to our APIs using IPv4 or IPv6 have equally secure connections and use the same strong TLS encryption.

      However, some customers may see a performance improvement if IPv6 allows them to avoid NAT.

      Was this article helpful?
      Related articles
      What's Next