This page contains information on the usage and behaviour of HTTP and HTTPS file transfer services.
The HTTP file transfer service provides an HTML-based interface designed to work in any web browser, including older versions of browsers which don’t have JavaScript or cookie features available or enabled.
The HTTP protocol is implemented based on RFC 2616, while the HTTPS protocol is based on RFC 2818.
The HTTP service allows the same level of file access as the other available file transfer services such as FTPS or SFTP.
When using the HTTP file transfer service in a browser without JavaScript or cookies, some of the advanced features are not available.
Basic features, listed below, are supported:
In order to have the HTTP file transfer service available for browsers without cookies, we chose to use the simple and standard HTTP Basic Auth method.
This allows all browsers to authenticate, including command line tools such as cURL or Wget.
Danger
HTTP Basic Auth will send credentials in a plain text encoding and it is not recommended to use HTTP Basic Auth over unsecured HTTP connections.
Note
Our roadmap includes adding support for multiple authentication methods and we are working on providing the standard HTTP Digest and HTTP NTML authentication methods, a cookie-based authentication method as well as passwordless authentication based on SSL client certificates.
In the case that you require a specific authentication method, please contact us.
HTTP service provides a simple JSON-based API for accessing and managing files over the HTTP protocol.
The current JSON API is neither REST nor JSON-RPC.
When responding to path related requests, the response will contain the following additional headers:
For requests with invalid headers or content, the response code is 400 Bad Request. The body will contain a message with JSON-formatted error details:
HTTP/1.1 400 Bad Request
{"errors": [{"message": "Problems parsing JSON"}]}
For requests which have valid headers and valid content, but which cannot be processed, the response is HTTP/1.1 422 Unprocessable Entity:
HTTP/1.1 422 Unprocessable Entity
{
"errors": [
{"message": "Text message describing the error."}
]
}
Note
When the URL for a folder request does not end with an / (slash character), the server will respond with a redirect toward the associated URL ending with a slash.
HTTP content negotiation is a complex mechanism. So, to keep our API simple, as long as the content type of your request is application/json, the response will also be JSON-formatted.
The file download request URL is structured as follows:
https://sub.example.com:PORT/home/PATH/TO/FILE
In the above example, the URL will trigger a download request for /PATH/TO/FILE.
Both GET and HEAD request methods are supported.
There is also support for the If-Modified-Since request header and the server will reply with the standard 304 Not Modified response header if the file has not been modified since the requested date.
A file download request would look like:
GET /home/PATH/TO/file HTTP/1.1
The response will be:
HTTP/1.1 200 OK
Server-Path: /PATH/TO/file
FILE_CONTENT_HERE
The folder listing request URL is structured as follows:
https://sub.example.com:PORT/home/PATH/TO/FOLDER/
In the above example, the URL will trigger a folder listing request for /PATH/TO/FOLDER.
The default response content type is HTML. To request the content as JSON, you should use:
GET /home/PATH/TO/FOLDER/ HTTP/1.1
Content-type: application/json
The response will look like this:
HTTP/1.1 200 OK
Server-Path: /PATH/TO/FOLDER
Content-Type: application/json
{"content": [
{
"name": "some-folder",
"is_directory": true,
"modified": 1427291663.52,
"size": 0
},
{
"name": "other-folder",
"is_directory": true,
"modified": 1427291076.37,
"size": 0
},
{
"name": "some-file.TXT",
"is_directory": file,
"modified": 1427291184.78,
"size": 12133
},
{
"name": "other.PDF",
"is_directory": false,
"modified": 1427291083.33,
"size": 7073
}
]
}
Note
modified field is in POSIX/Unix time formatted as seconds with decimals representing the milliseconds.
Note
If you consume this JSON in JS, note that Date() is instantiated with milliseconds, so you will need to use new Date(json_value * 1000).
You can execute folder operations by sending a POST request with an application/json content type to a folder path.
Here is the list of supported command: * delete * create-folder * create-folder-if-missing
Below you will find example of their usage.
The following example will delete /home/path/to/folder/child-file:
POST /home/path/to/folder
Content-type: application-json
{
"commands": [
{
"command": "delete",
"target": "child-file"
}
]
}
You can recursively remove folders. The following example will delete a folder located at /home/path/to/folder/child-folder together with all its members and children:
POST /home/path/to/folder/
Content-type: application-json
{
"commands": [
{
"command": "delete",
"target": "child-folder"
}
]
}
The following example will create a new folder /home/path/to/folder/new-folder-name:
POST /home/path/to/folder/
Content-type: application-json
{
"commands": [
{
"command": "create-folder",
"target": "new-folder-name"
}
]
}
The following example will create a new folder at /home/path/to/folder/new-folder-name and will not raise an error if the folder already exists:
POST /home/path/to/folder/
Content-type: application-json
{
"commands": [
{
"command": "create-folder-if-missing",
"target": "new-folder-name"
}
]
}
You can combine multiple commands into a single request:
POST /home/path/to/folder/
Content-type: application-json
{
"commands": [
{
"command": "delete",
"target": "child-file"
},
{
"command": "create-folder",
"target": "sibling-folder"
},
{
"command": "delete",
"target": "other-file"
}
]
}
Note
Command names are case-sensitive. The command target is also case-sensitive, with the exception of files stored on NTFS or other case-insensitive file systems.
If all commands have been successful, the response will be:
HTTP/1.1 200 OK
If the request is not well formatted, the response will be 400 and no action will be performed:
HTTP/1.1 400 Bad Request
Content-type: application-json
{"errors": [{"message": "Details about what is not right."}]}
When at least one command fails, the response will contain a result combining the results of all commands. For successful commands the message is null. Beside the error message, each error will contain the associated target:
HTTP/1.1 422 Unprocessable Entity
Content-type: application-json
{
"errors": [
{"target": "child-file", "message": null},
{"target": "child-folder", "message": "Invalid name 'child-folder'."},
{"target": "other-file", "message": null},
]
}
HTTP service provides a browser friendly API for managing files over HTTP, based on POST request and data encoded using multipart/form-data.
For example, the request to create a new folder with name new-folder is:
POST /home/path/to/folder/ HTTP/1.1
Content-type: multipart/form-data; boundary=----Browser4sDB61mTyhxl1VS9
------Browser4sDB61mTyhxl1VS9
Content-Disposition: form-data; name="action"
create-folder
------Browser4sDB61mTyhxl1VS9
Content-Disposition: form-data; name="new-folder"
test-folder
------Browser4sDB61mTyhxl1VS9--
To delete multiple members of the folder the request can be:
POST /home/path/to/folder/ HTTP/1.1
Content-type: multipart/form-data; boundary=----BrowserDpxASFZnpR6imXgG
------BrowserDpxASFZnpR6imXgG
Content-Disposition: form-data; name="action"
delete-members
------BrowserDpxASFZnpR6imXgG
Content-Disposition: form-data; name="selected-members"
tmp0gdd8j.txt
------BrowserDpxASFZnpR6imXgG
Content-Disposition: form-data; name="selected-members"
tmp0t2rw4.pdf
------BrowserDpxASFZnpR6imXgG
Content-Disposition: form-data; name="selected-members"
tmp0t6kdr.csv
------BrowserDpxASFZnpR6imXgG--
Name of the requested action.
| type: | string |
|---|---|
| available values: | |
|
|
HTTP/HTTPS file transfer service can handle HTTP/1.1 client requests made using the 100 (Continue) status. This allows the client sending the request message with a given request body to determine whether the origin server is willing to accept the request (based on the request headers) before the client sends the request body.
For example, it might be inappropriate or highly inefficient for the client to send a large body if the server rejects it solely based on the body size.