Introduction and Authentication
The LiquidFiles API is a REST based API that primarily uses XML 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.
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:
In this case, the users API key is: gXvoqaFzd1jYQ9f13sPO06. 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 'Content-Type: text/xml' --user gXvoqaFzd1jYQ9f13sPO06:x https://liquidfiles.example.com/message
A couple of things to note. We need to set the Content-Type to xml (or text/xml to make it a valid mime-type, can also be application/xml). An alternative to using the content type is to append .xml to the URL to make it: https://liquidfiles.example.com/message.xml. This work on any URL in the API that uses XML.
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 '/message' 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.
Back a few years ago, 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:
|GET||Request access to some data. An example would be to list all available messages.|
|POST||Send Data. You will use this when sending messages.|
|DELETE||To delete an uploaded files (or other data as we expand the API).|
|PUT||To change a value. As we expand the API, you may use this to change a user from a local user to an admin, and similar functions.|
Response Status Codes
The LiquidFiles appliance will respond with a http status code. The most common status codes would include:
|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.|