Recommend S3 API for basic needs

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 https://github.com/yakovkhalinsky/backblaze-b2/issues/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

[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.

[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.