https://man.liquidfiles.com
LiquidFiles Documentation

The most common use of the API is to use it to send files.

Before sending our first file, a little bit a background information is required. When LiquidFiles sends a file, it really sends a message, with files attached to it. Same with a FileLink, it's a FileLink object with a file (attachment) attached to it. The Message or FileLink is what has all the meta data such as expiration and it's when the message expires that the files attached to it gets deleted as well.

Sending large files is difficult. If it was easy, a product such as LiquidFiles wouldn't be needed in the first place. To upload the actual file to the LiquidFiles system, we have two alternate methods. We can either use a combination of html form based uploads, or we can use straight JSON.

JSON based uploads

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

{"message":
  {"attachments": [{
      "filename":"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 application. 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 sent 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 (all files combined) you can send with this method is 100 Mb. While this should still be plenty for most applications, if you send files near that size on a regular basis, it's the recommendation to switch to the form based upload mechanism instead.

When sending files using JSON, you add it directly into the message. Please see the Sending Files API documentation for an example how to send files directly using Base64 encoded file data.

HTML form based uploads

This is a much more efficient way of sending files. The only real problem with it is that it doesn't conform to the API standard way of using JSON for everything, and can lead to some cludges when you're implementing this into your application.

It's based on this simple html form:

<form action="https://liquidfiles.example.com/attachments" enctype="multipart/form-data" method="post">
  <input type="file" name="Filedata" filename="filename.ext">
</form>

which would lead to the raw data being transmitted like this:

Content-type: multipart/form-data; boundary=AaB03x

--AaB03x
content-disposition: form-data; name="Filedata"; filename="filename.ext"
Content-Type: image/gif

... contents of filename.ext ...
--AaB03x--

While this may not look very different. It will enable us to send binary data as content, and the webserver can intercept this before the web application sees it and so on. Much more efficient.

This will also send the files separate from the message, and we'll just include references to the files when sending the message.

Request

Request URL: /attachments
Request VERB: POST
Parameters:
  Filedata:      # MultiPart:  The html multiplart file data
  pool_id:       # String:     (optional) If this file is for a pool.
Response:
  Attachment ID  # String.  A unique string representing the attachment id. This will be used to reference the
                 #          files in the message.

Example Request using curl

#!/bin/sh

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.comapny.com"

# Uploading the actual file and get attachment id for each file
attachment_id=`curl -X POST --user "$api_key:x" -F Filedata=@bigfile.zip $server/attachments`

Please note in this example that curl syntax of @bigfile.zip means to load the data from the file bigfile.zip. If you enter '-F Filedata=bigfile.zip' without the @ it means send the string "bigfile.zip" as Filedata, that won't send the data from the file.

Example Response

8cvrfQ6zSQhLccJnKGzSV5

Please note with this response that it's not your normal JSON formatted type response. It's just the attachment id.

Example Request using curl with Pool ID

#!/bin/bash

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.comapny.com"

# Uploading the actual file and get attachment id for each file
attachment_id=`curl -X POST --user "$api_key:x" -F Filedata=@bigfile.zip -F pool_id='partner-pool' $server/attachments`

Please note in this example that curl syntax of @bigfile.zip means to load the data from the file bigfile.zip. If you enter '-F Filedata=bigfile.zip' without the @ it means send the string "bigfile.zip" as Filedata, that won't send the data from the file.

Example Response

8cvrfQ6zSQhLccJnKGzSV5

Please note with this response that it's not your normal JSON formatted type response. It's just the attachment id.