Recommend S3 API for basic needs

[MarcGuiselin]

Backblaze has done a very good job implementing compatibility with S3. See: https://help.backblaze.com/hc/en-us/articles/360047425453-Getting-Started-with-the-S3-Compatible-API

Why use the S3 api instead of this library?

• Consistently faster uploads without needing for retries/waiting (see explanation below)
• Better typescript support (none of the b2 server responses are typed)
• Simpler implementation
• Works with B2's file versioning by default (see explanation below)
• It might be a smaller overall dependency size (when tree-shaken)

Using the S3 api

A simple file upload to backblaze can be done like so with the AWS sdk:

import {
  S3Client,
  PutObjectCommand,
  DeleteObjectCommand,
} from '@aws-sdk/client-s3'

const b2 = new S3Client({
  endpoint: `https://s3.${REGION}.backblazeb2.com`,
  region: REGION,
  credentials: {
    // Must have both read and write permissions on BUCKET_NAME
    accessKeyId: B2_ID,
    secretAccessKey: B2_KEY,
  },
})

await b2.send(
  new PutObjectCommand({
    Bucket: BUCKET_NAME,
    Key: 'my file path',
    Body: 'body',
    ContentType: 'mimetype',
  })
)

Uploads are faster as this api can be used out of the box and correctly interfaces with backblaze's backend. No need to mess with retries,

In my opinion, this should be recommended as the way forward for new developers looking to get started with B2.

Flaws with this library

Issue #90 highlights one of the MAJOR issues of this library, namely that out of the box it does not support the correct implementation of file uploads as per the official b2 docs here (for example this library does not call b2_get_upload_url again to get a new auth token when the server responds with a 503). As a result, in my own testing uploads can take a few seconds to several of minutes for small 200kb files. It also doesn't set the recommended X-Bz-Info-src_last_modified_millis by default, so you have to add this header yourself otherwise b2's file versioning won't work properly.

You have to implement these things yourself, and this comes with some trial and error and a lot of reading through the B2 docs.

@cdhowie has done a good job addressing the problems with uploading files with @gideo-llc/backblaze-b2-upload-any, but his library is missing typescript support.

When to use this library

• If you need better control over permissions, such as only reading or writing files, the S3 api will throw an error
• Implementing any action not listed in the S3 compatibility page: https://www.backblaze.com/b2/docs/s3_compatible_api.html
• For advanced usage of B2 (As mentioned by @cbess), including usage of backblaze lifecycle rules

[cbess]

I mostly agree with your sentiments. I concur, using the S3 API is good for basic needs, but for more advanced usage this library is the most helpful.

[cbess]

@MarcGuiselin In light of the above, for the issue to be actionable, I would change the title from New developers should migrate to the S3 Api to Recommend S3 API for basic needs.

[MarcGuiselin]

I mostly agree with your sentiments. I concur, using the S3 API is good for basic needs, but for more advanced usage this library is the most helpful.

Absolutely. Advanced usage of B2, including backblaze lifecycle rules, are only supported by the native B2 api.

[metadaddy]

The official Backblaze position is that

if your app is already written to work with S3, if you’re using tools that are written to S3, or if you’re just unsure, the S3 Compatible API is a good choice

As Backblaze's Chief Developer Evangelist, I'll go further and say that, in general, you should use the S3 Compatible API as far as you can, and only use the B2 Native API for Backblaze-specific features.

[Relivest]

@metadaddy How can I use s3 api with cloudflare alliance? I use my s3 binding to proxy on my cdn, but it detects it as a b2 api instead of an s3 api.

[lisotton]

I noticed that from time to time the S3 compatible API has some issues. I upload millions of small files per week and for example yesterday ~5% of the uploads via S3 compatible API were timing out.

I changed to use this library and use the B2 API and the upload were working fine.

@metadaddy could this be a problem in the way the S3 Compatible API balances the requests throughout many servers?