https://man.liquidfiles.com
LiquidFiles Documentation

Before uploading our first file, a little bit a background information is required. To upload the actual file to the LiquidFiles system, we have three different methods — Binary Uploads, HTML Form Based Uploads or JSON based uploads.

Upload Method Overview

JSON Based Uploads

The typical modern web based API format is JSON, which is a text based format that is also used by LiquidFiles for all LiquidFiles API functions. It's a simple, well documented format that is strictly text based, which means that we have to Base64 encode binary data (which basically stretches 3 bytes of binary data over 4 bytes only using text characters) that is a lot less efficient than either the binary or the HTML based upload methods, but has the benifit of being able to be easily defined in API. If you're sending smaller files (sensitive PDF documents that are fairly small for instance), this is the easiest to use.

Binary Uploads

This is the method that's used by all the builtin LiquidFiles functions. So if you upload a file using the web interface, the Outlook plugin, Mac plugin and so on, it's using the binary upload method. It's basically sending the raw binary data to the LiquidFiles system and is the most efficient way of uploading files to a web server. It is also probably the most complex/least supported in terms of support from external libraries if you want to incorporate this into an existing project.

HTML Form Based Uploads

This is the previous method used by the builtin LiquidFiles functions and mimics what happens when someone uses a HTML (multipart/form-data) form element to upload files. This is now considered legacy and you should if possible use the Binary Upload method instead. The HTML Form Based Upload is the method that's been used on the web for uploading files since it was first introduced way back in the 1990s. It's a very well documented way of uploading files, but adds some preamble to the actual data and requires web server plugins to process the file on the server side so is not as efficient as uploading files using the binary upload method.

Please see the Form Based Attachment Upload documenation for further information.

JSON based uploads

JSON is what's being used for all other aspects of the LiquidFiles API but when it comes to sending files it poses a bit of a problem. Consider the following example request:

{"file":
  {
    "name":"logo.gif",
    "data":?????
  }
}

Since JSON is a text based protocol, we can't just insert binary data in it in the "data" tag. The standard programatical solution to problems like this is to Base64 encode the binary data into something that can be transmitted over text. This works, but using Base64 encoding has several problems though, some of which include:

  • Aproximately 33% file size increase. We're taking 3 bytes or binary data and spreading over 4 bytes using only the text writable characters. With large files, this leads to a significant increase.
  • It's impossible to do any fancy server side file handling. The entire JSON request will be loaded into the web applications memory. Normally when files are sent using LiquidFiles, the web server (nginx) takes care of the binary file data and the web application only deals with moving files around but the actual file data never passes through the web application. This keeps LiquidFiles fast and efficient. If you where to send a 1Gb file using this method, first it would be 1.3Gb transferred (Base64) and this would be loaded (twice - raw Base64 data and decoded) into the memory of LiquidFiles before it could write it to disk. This is very slow and inefficient.
  • With these limitations, the maximum message size you can upload with this method is 100MB. While this should still be plenty for a lot of applications, if you upload files near that size on a regular basis, it's the recommendation to switch to the form based upload mechanism instead.

Request Info and Parameters for JSON based Uploads

Request Info
Info Value
Request URL /shares/_share_id_/folders/_folder_id_/files
Request VERB POST
Request Parameters
Parameter Type Description
name String The filename of the file you're uploading.
data String The data of the file, encoded in Base64 encoding (max size 100MB).
content_type String (Optional) The Content-Type of the uploaded file. If not present the server will calculate the Content-Type.
checksum String (Optional) The SHA-256 checksum of the uploaded file. If not present the server will calculate the SHA-256 checksum.
crc32 String (Optional) The CRC32 checksum of the uploaded file. If not present the server will calculate the CRC32 checksum.

To upload files using Base64 Encoding, please see the following example using curl and bash:

cat <<EOF | curl -s -X POST -H "Content-Type: application/json" --user "nkpIxMK9ucUUE7FvfNpdAf:x" -d @- https://liquidfiles.example.com/shares/project-alpha/folders/root/files
{"file":
  {
    "name":"Presentation1.pptx",
    "data":"`base64 /path/to/Presentation1.pptx`"
  }
}     
EOF

Binary Data Uploads

There's two parts to a HTML POST statement, it's the body of the POST and it's the parameters. In a traditional HTML post, the parameters are hidden within the body of the POST, but there's no reason they have to. With the LiquidFiles binary upload method, we're actually using GET style parameters to pass additional information. It looks like this:

POST https://liquidfiles.example.com/shares/someshare/folders/somefolder/files/binary_upload?name=somefile.ext
RAW BINARY FILEDATA
Request Info
Info Value
Request URL /shares/_share_id_/folders/_folder_id_/files/binary_upload
Request VERB POST
Request Parameters
Parameter Type Description
name String The filename of the uploaded file.
chunks Integer (optional) When uploading files in chunks (in pieces), these are the total number of pieces there is.
chunk Integer optional and required when chunks is set) When uploading files in chunks, this is the current chunk number, with the first chunk being chunk number 0 (zero).
Response Parameters
Parameter Type Description
id String The Unique ID for the share.
folder_id String The ID for the parent folder.
name String The Name of the Share.
size Integer The size of the file in Bytes.
size_to_human String The size of the file in human readable format.
content_type String The Content-Type of the file.
checksum String The SHA-256 Checksum of the file.
crc32 String The CRC32 Checksum of the file.
av_scanned Boolean If the file has been AV scanned or not.
av_infected Boolean If the file is AV infected.
deleted Boolean If the file has been deleted or not.
created_at DateTime When the file was created
update_at DateTime When the file was last updated

Example Using curl

The Response has been formatted for readability (added indendation and linebreaks).

curl POST --user "DaDMcRpYEFUsxSUjUozMoU:x" -H "Content-Type: application/json" --data-binary "@someimage.gif" https://liquidfiles.example.com/shares/project-1/folders/folder-1/files/binary_upload?name=someimage.gif

{"file":
  {
    "id":"someimage-gif",
    "folder_id":"folder-1",
    "name":"someimage.gif",
    "size":49656,
    "size_to_human":"48 KB",
    "content_type":"image/gif",
    "checksum":"a5f21ee04ff2ff7ac191a76bf5bf432ac32eda5f2599bb2e876568d1376a0984",
    "crc32":"9d378437",
    "av_scanned":false,
    "av_infected":false,
    "deleted":false,
    "created_at":"2021-04-28T22:35:08.983Z",
    "updated_at":"2021-04-28T22:35:08.983Z",
    "processed":false,
    "processed_at":null
  }
}