LiquidFiles Documentation

Introduction and Authentication

The LiquidFiles API is a REST based API that uses JSON to interact with it.

With the API, you can send and receive files from other resources and since it's based on current web standards, you can use pretty much any language or any platform, as long as you can make standardised web calls.

Throughout the API documentation, we refer a lot to examples using curl which is a cross platform tool that is easy to add parameters with to test responses from the system. Curl is available on most platforms including Windows at http://curl.haxx.se/download.html.

Authentication

The LiquidFiles API uses http basic authentication using API keys. You can view your API key by looking in your Account page on the LiquidFiles system. You will see something similar to this:

images/api/introduction_and_authentication/api_key.png

In this case, the users API key is: OhuHzkYns0z2vMsTb7CZhK. To authenticate to the LiquidFiles system, you use the API key as the username. The password doesn't matter. An example with curl would be:

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  --user gXvoqaFzd1jYQ9f13sPO06:x https://liquidfiles.example.com/messages/inbox

Curl doesn't allow us to use an empty password so in this case we use the letter 'x' but we could have set anything as the only thing being looked at is the username as the API key. The relative url '/messages/inbox' will list all messages for the user with the API key: gXvoqaFzd1jYQ9f13sPO06.

Please note that the API key is persistent and won't change unless the user (or an admin) resets it.

HTTP Basic Authentication

If you want to manually create your own authentication header, if your language doesn't have support for adding http basic authentication in a simple way, the HTTP Header looks like:

Authorization: Basic Z1h2b3FhRnpkMWpZUTlmMTNzUE8wNjo=

Where Z1h2b3FhRnpkMWpZUTlmMTNzUE8wNjo= is Base64 encoded, created using something like:

Base64(gXvoqaFzd1jYQ9f13sPO06:)

Base64 in this case is a generic function and would need to be replaced by the equivalent command for your programming language of choice. Please note the colon at the end of the API key.

You can also test by entering an API key in the following field:

Resulting Authorization Header

Authorization: Basic Z1h2b3FhRnpkMWpZUTlmMTNzUE8wNjo=

Content-Type and Accept Headers

If you look at the example above again, you will see two headers, Content-Type and Accept:

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  --user gXvoqaFzd1jYQ9f13sPO06:x https://liquidfiles.example.com/messages/inbox
  • The Accept header tells what you format I want to receive the response in.
  • The Content-Type header tells what format you are sending the request data in.

The only supported value for both when using the API is application/json.

As a side note, when the browser is sending the Accept and Content-Type headers set to text/html, this is how LiquidFiles knows to treat the request as a browser HTML session instead of an API session. And given that this is the API section, you need to set both Accept and Content-Type to application/json or the LiquidFiles system won't know to treat this as an API request.

Upcoming Deprecation Warning

LiquidFiles up to v3.6 will treat requests with Content-Type set to application/json with no Accept header as an API request. This has lead to some internal issues and future versions of LiquidFiles will require the Accept header to be set as well as the Content-Type header.

HTTP Verbs

Going back a few years, the entire web used only either GET requests or POST requests and seeing other request types was seen as a potential security problem. With modern REST based standards, this has changed and we now frequently utilise more of the available http verbs at our disposal. These would include:

VerbDescription
GET List or view data. An example would be to list all available messages.
POST Create a user, group or other object, or to send data. You will use this when sending messages.
DELETE To delete an uploaded file, delete a user, group or other data.
PUT To change a value of an already created object, like changing the download authorization setting of an existing FileLink.

Response Status Codes

The LiquidFiles appliance will respond with a http status code. The most common status codes would include:

CodeDescription
200 Everything went fine (user found, file uploaded ok, message sent successfully)
401 Unauthorized, API key or User authentication failed
422 Something went wrong and the request could not be completed (Email and/or password incorrect, invalid file, invalid message)
500 Something went very wrong. This could happen if the system is expecting a value between 0-100 and you send a 1Mb picture of a cat, and similar situations.