File Versions

To keep your data safe, even if you upload a bad file or delete the wrong file, Backblaze B2 Cloud Storage lets you keep a history of previous versions of each file that you store. Not only can you keep previous versions of a file, but Backblaze B2 can track when a file is deleted and when it is returned which allows you to keep a full history.

The first time you upload a file called puppy.jpg, you have only one version of the file, so it is clear which one you get when you download that file.

A file has a list of versions with the newest version listed first. When you download a file by name, you always get the most recent version, the first one in the list. If you want an older version, you can find its File ID, and then download it.

The following example shows an upload of a new file called puppy.jpg:

If you upload another file with the same name, there are now two versions in the list, with the newest one first:

At this point, if you download “puppy.jpg,” you will get the new one. You can still download either puppy image using its file ID.

The b2_list_file_names operation returns one entry for each file name. So, at this point, it returns just one file name with the file ID of the more recent version. If you want to see all of the versions of the file, you can use the b2_list_file_versions operation, which lists both versions of “puppy.jpg.”

The b2_hide_file operation makes it look like the file has been deleted, without removing any of the history. It adds a new version of the file with a "hide marker" that says the file is no longer there.

With the file hidden, if you download the file by name, a 404 error is returned that says that the file is not there.

If you upload yet another cute puppy picture, a new version is added, which is the one that you get when you download the file by name. The fact that an older version was hidden is still in the history.

The b2_list_file_versions operation returns all of this information. The following example shows how results may look:

{
    "files" : [
        {
            "fileId": "4_z4a48fe8875c6214145260818_f0000000000823564_d20150725_m091433_c001_v0000123_t0104",
            "fileName": "puppy.jpg",
            "action": "upload",
            "uploadTimestamp": 1437815673000,
        },
        {
            "fileId": "4_z4a48fe8875c6214145260818_f0000000057265835_d20150723_m160005_c001_v0000123_t0104",,
            "fileName": "puppy.jpg",
            "action": "hide",
            "uploadTimestamp": 1437667205000,
        },
        {
            "fileId": "4_z4a48fe8875c6214145260818_f0000000000562156_d20150721_m045924_c001_v0000123_t0104",
            "fileName": "puppy.jpg",
            "action": "upload",
            "uploadTimestamp": 1437454764000,
        },
        {
            "fileId": "4_z4a48fe8875c6214145260818_f000000000000472a_d20150721_m032942_c001_v0000123_t0104",
            "fileName": "puppy.jpg",
            "action": "upload",
            "uploadTimestamp": 1437449382000,
        }
    ]
}

Lastly, you can use the b2_delete_file_version operation to delete file versions; however deleting a file version cannot be undone. You can use this operation to clean up old versions of a file that you no longer need. The following example shows the results if you remove the first puppy that you uploaded: 

You can also delete the marker that indicates that a file is hidden. If, at this point, you delete the newest version and the deletion marker, you now have just one version:

To summarize, the following API calls are related to file versions:

• b2_upload_file This operation creates a new file version. Because it is the newest version,this is the one that is returned when you download a file by name.
• b2_download_file_by_id This operation downloads a specific version of a file by the given file ID.
• b2_download_file_by_name This operation downloads the most recent version of the file. If the file does not exist, or the most recent version is "hidden," a 404 message is returned.
• b2_hide_file This operation creates a "hidden" marker as the most recent version of the file. If you download the file by name, a 404 message is returned.
  
• b2_delete_file_version This operation permanently deletes the file version and all of its data as if you never uploaded that version.
• b2_list_file_names This operation returns file names for the bucket, in alphabetical order, beginning at a given point.
• b2_list_file_versions This operation returns a list of all versions of all files that are in a bucket, sorted by file name, then by upload time. You can restrict the list to return only the version for a given file name.