File IO¶

Provides a REST-like API for uploading and downloading files to and from iRODS.

Error handling¶

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.

Downloading¶

URL Path: /secured/fileio/download

HTTP Method: GET

URL Path: /secured/filesystem/display-download

HTTP Method: GET

Request Query Parameters:

path - The path to the file in iRODS to be downloaded.

Error Codes:

ERR_INVALID_JSON (wrong content-type or JSON syntax errors)
ERR_BAD_OR_MISSING_FIELD (JSON field is missing or has an invalid value)
ERR_MISSING_QUERY_PARAMETER (Query parameter is missing)
ERR_NOT_A_USER (invalid user specified)
ERR_DOES_NOT_EXIST (File request doesn't exist)
ERR_NOT_READABLE (File requested isn't readable by the specified user)

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.

Uploading¶

URL Path: /secured/fileio/upload

HTTP Method: POST

Request Query Parameters:

dest - The path to the iRODS folder where the file(s) will be uploaded.

Request Form Fields:

file - The contents of the file to be uploaded.

Error Codes:

ERR_MISSING_FORM_FIELD (One of the form data fields is missing)
ERR_MISSING_QUERY_PARAMETER (Query parameter is missing)
ERR_NOT_A_USER (Invalid user specified)
ERR_DOES_NOT_EXIST (Destination directory doesn't exist)
ERR_NOT_WRITEABLE (Destination directory isn't writeable)

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 Uploads¶

URL Path: /secured/fileio/urlupload

HTTP Method: POST

Error codes:

ERR_INVALID_JSON (Missing content-type or JSON syntax error)
ERR_BAD_OR_MISSING_FIELD (Missing JSON field or invalid JSON field value)
ERR_MISSING_QUERY_PARAMETER (One of the query parameters is missing)
ERR_NOT_A_USER (Invalid user specified)
ERR_NOT_WRITEABLE (Destination directory isn't writeable by the specified user)
ERR_EXISTS (Destination file already exists)
ERR_REQUEST_FAILED (General failure to spawn upload thread)
ERR_INVALID_URL (URL that was passed in couldn't be used)

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.

Save¶

URL Path: /secured/fileio/save

HTTP Method: POST

Error Codes:

ERR_INVALID_JSON (Missing content-type or JSON syntax error)
ERR_BAD_OR_MISSING_FIELD (Missing JSON field or invalid JSON field value)
ERR_NOT_A_USER (Invalid user specified)
ERR_DOES_NOT_EXIST (The destination directory does not exist)
ERR_NOT_WRITEABLE (The destination directory is not writable by the user)
ERR_FILE_SIZE_TOO_LARGE (The size of the "content" field is larger than the terrain.fileio.max-edit-file-size config setting)

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'

Save As¶

URL Path: /secured/fileio/saveas

HTTP Method: POST

Error Codes:

ERR_INVALID_JSON (Missing content-type or JSON syntax error)
ERR_BAD_OR_MISSING_FIELD (Missing JSON field or invalid JSON field value)
ERR_NOT_A_USER (Invalid user specified)
ERR_DOES_NOT_EXIST (The destination directory does not exist)
ERR_NOT_WRITEABLE (The destination directory is not writable by the user)
ERR_EXISTS (The destination file already exists)

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.