Introduction

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.

Content-Type and Accept Headers

If you look at a typical API request, you will see two headers, Content-Type and Accept:

curl -X POST --user gXvoqaFzd1jYQ9f13sPO06:x \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"user": {"email": "jdoe@company.com"}}' \
     https://liquidfiles.example.com/admin/users

• 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. In the example above, that's {"user": {"email": "jdoe@company.com"}} which is data in JSON format so the Content-Type is set to application/json.

The only supported value for Accept is application/json when using the API. The typical value for Content-Type is also application/json but lets say you're uploading a file "image.gif" then the Content-Type (what you're sending) would be image/gif where's the Accept (how you want this to be processed, or how you want the response) would be application/json.

curl -X POST --user gXvoqaFzd1jYQ9f13sPO06:x \
     -H "Accept: application/json" \
     -H "Content-Type: image/gif" \
     --data-binary @image.gif \
     https://liquidfiles.example.com/message/attachments/upload

As a side note, when the browser is sending the Accept header set to text/html, this is how LiquidFiles knows to treat the request as a browser HTML session instead of an API session. Accept text/html is also the default in many tools so if you don't set Accept to application/json specifically, it will likely default to text/html and you'll receive a HTML page as a response.

You don't need to set the Content-Type header when you're not sending any data. For instance the following API call:

curl -X GET --user gXvoqaFzd1jYQ9f13sPO06:x \
     -H "Accept: application/json" \
     https://liquidfiles.example.com/message/inbox

-X GET in the example above is not necessary because curl will default to GET if no method is set. And you can see that in this case we're not sending any data so no need for a Content-Type header, only the Accept header is needed to tell LiquidFiles this is a JSON API request.

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:

Response Status Codes

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