Provides a REST-like API for uploading and downloading files to and from iRODS.
If you try to hit an endpoint that doesn’t exist, you’ll get a 404.
For all other errors, you should receive a 500 HTTP status code and a JSON body in the following format:
{
"error_code" : "<Scruffian error code>"
}
Most errors will return other contextual fields, but they will vary from error to error. For programmatic usage, only depend on the three fields listed above.
Each section listed below lists the error codes that you may encounter. In addition to these, you may run into the ERR_UNCHECKED_EXCEPTION, which means that an uncaught exception was encountered.
URL Path: /secured/fileio/download
HTTP Method: GET
URL Path: /secured/filesystem/display-download
HTTP Method: GET
Request Query Parameters:
Error Codes:
Curl Command:
curl -H "$AUTH_HEADER" 'http://127.0.0.1:31370/secured/fileio/download?path=/iplant/home/testuser/myfile.txt'
This will result is the file contents being printed out to stdout. Redirect to a file to actually get the file.
When using fileio/download, it’s always downloaded as an attachment and the content-type is always application/octet-stream. When using display-download, attachment is a parameter that can be passed along.
These endpoints delegate to data-info’s GET /data/path/:zone/:path endpoint, with some processing.
URL Path: /secured/fileio/upload
HTTP Method: POST
Request Query Parameters:
Request Form Fields:
Error Codes:
Response Body:
A success will return JSON like this:
{
"file": {
"id": "<path to the file>",
"path": "<path to the file>",
"label": "<basename of the file path>",
"permission": "own",
"date-created": <seconds since the epoch>,
"date-modified": <seconds since the epoch>,
"file-size": <size in bytes>
}
}
Curl Command:
Uploading is handled through multipart requests:
curl -H "$AUTH_HEADER" -F file=@testfile.txt "localhost:31325/secured/fileio/upload?dest=/iplant/home/testuser"
Notice that the dest value points to a directory and not a file.
This endpoint delegates to data-info’s POST /data endpoint.
URL Path: /secured/fileio/urlupload
HTTP Method: POST
Error codes:
Request Query Parameters:
Request Body:
{
"dest" : "/iplant/home/testuser/",
"address" : "http://www.google.com/index.html"
}
Response Body:
On success you should get JSON that looks like this:
{
"msg" : "Upload scheduled.",
"url" : "<URL>",
"label" : "<URL base filename>",
"dest" : "<destination in irods>"
}
On on error, you’ll either get a stacktrace or JSON that looks like this:
{
"msg" : "<JSON passed in through the request>",
"error_code" : "ERR_REQUEST_FAILED"
}
If the URL passed in is incorrect, then the error message will look like this:
{
"error_code" : "ERR_INVALID_URL",
"url" : "<URL Passed in>"
}
Curl Command:
curl -H "$AUTH_HEADER" -d '{"dest" : "/iplant/home/testuser/", "address" : "http://www.google.com/index.html"}' http://127.0.0.1:31370/secured/fileio/urlupload
The ‘dest’ value in the JSON refers to the path to the directory in iRODS that the file will be saved off to. The filename of the file will be extracted from the path portion of the URL.
URL Path: /secured/fileio/save
HTTP Method: POST
Error Codes:
Request Body:
{
"content" : "This is the content for the file.",
"dest" : "/iplant/home/testuser/savedfile.txt"
}
Response Body:
{
"file": {
"id": "<path to the file>",
"path": "<path to the file>",
"label": "<basename of the file path>",
"permission": "own",
"date-created": <seconds since the epoch>,
"date-modified": <seconds since the epoch>,
"file-size": <size in bytes>
}
}
Curl Command:
curl -H "$AUTH_HEADER" -d '{"dest" : "/iplant/home/testuser/savedfile.txt", "content" : "This is the content for the file."}' 'http://127.0.0.1:31370/secured/fileio/save'
URL Path: /secured/fileio/saveas
HTTP Method: POST
Error Codes:
Request Body:
{
"content" : "This is the content for the file.",
"dest" : "/iplant/home/testuser/savedfile.txt"
}
Response Body:
{
"file": {
"id": "<path to the file>",
"path": "<path to the file>",
"label": "<basename of the file path>",
"permission": "own",
"date-created": <seconds since the epoch>,
"date-modified": <seconds since the epoch>,
"file-size": <size in bytes>
}
}
Curl Command:
curl -H "$AUTH_HEADER" -d '{"content" : "This is the content for the file.", "dest" : "/iplant/home/testuser/savedfile.txt"}' 'http://127.0.0.1:31370/secured/fileio/saveas'
This endpoint delegates to data-info’s POST /data endpoint, similarly to the upload endpoint, with some processing.