Edgio
Control Portal

Working with Files in the JSON-RPC Interface

The Origin Storage API lets you work with existing files, performing actions such as copying, moving, and listing files. These operations are available in the JSON-RPC interface only. See also Working With Methods Common to Files and Directories.
The Origin Storage API also lets you upload files. See the following for details:
Note that you can download files from Origin Storage, although this capability is outside of the JSON-RPC and HTTP interfaces.

Copy a File

Method name: fetchFileHTTP
Copies a file from one location to a different location. If desired, you can specify a new name for the destination file. The method works according to the following rules:
  • You cannot use wild cards.
  • The copy operation is performed asynchronously.
The method asynchronously submits the copy request to a queue where it waits with other requests.

Copy a File Using Named Parameters

JSON
1{
2  "method": "fetchFileHTTP",
3  "id": 4,
4  "params": {
5    "token": "e1254148-c557-4bdd-99ea-ffe76cd450ad",
6    "path": "/TreesOfEurope/DeciduousTrees.txt",
7    "uri": "http://{Account name}/
8            TreesOfSouthAmerica/DeciduousTrees.txt",
9    "flags": 1
10  },
11  "jsonrpc": "2.0"
12}

Parameter Descriptions

Parameter NameTypeDescription
tokenstrValid token from a call to login (JSON-RPC interface) or /account/login (HTTP interface). See Log In Using JSON-RPC and Log in Using the HTTP Interface, respectively.
pathstrThe destination path and file name
uristrThe URI for the source path and file name. Must use properly URL-encoded values for disallowed characters or an error is returned.
The root path of your account is http://{Account name}/

Example:
If you have a preview.mp4 file in a previews directory off the root path, you reference the file like this:
http://{Account name}/previews/preview.mp4
flagsintOptional
Additional processing instructions. Valid values:
- FF_CREATE_DESTDIR: Automatically create the destination directory if it does not exist
- 1: Equivalent to FF_CREATE_DESTDIR

Return Codes

  • 0: success
  • -4: queue failure
  • -13: invalid flags
  • -14: invalid source uri
  • -56: too busy - concurrency reached (wait and try again)
  • -10001: invalid token
For a list of error codes not specific to fetchFileHTTP, see Global Error Codes.

Response Data

Returns only the codes discussed in Return Codes. Does not return any data structures.

Python Sample Requests

Using named parameters, copy example4.jpg in the root directory and rename the copy to example3.jpg:
Python
1>>> api.fetchFileHTTP(token, '/example3.jpg', 'http://{Account name}/example4.jpg', 1)
20

Delete a File

Method name: deleteFile
Deletes a file from the specified location. If the file is successfully deleted, the system sets the parent directory’s mtime (last modified time) to the current system time.

Delete a File Using Named Parameters

JSON
1{
2  "method": "deleteFile",
3  "id": 5,
4  "params": {
5    "token": "d6835f68-7bd4-4a29-9c40-54fbaeeb2444",
6    "path": "/TreesOfEurope/DeciduousTrees.txt"
7  },
8  "jsonrpc": "2.0"
9}

Deleta a File Using Positional Parameters

Positional parameters must be applied in the same order shown in the named parameters sample. Example:
JSON
1{
2  "method": "deleteFile",
3  "id": 4,
4  "params": [
5    "1ee13c07-1f50-4c05-8f89-d5779e17332b",
6    "/TreesOfEurope/DeciduousTrees.txt"
7  ],
8  "jsonrpc": "2.0"
9}

Parameter Descriptions

Parameter NameTypeDescription
tokenstrValid token from a call to login (JSON-RPC interface) or /account/login (HTTP interface). See Log In Using JSON-RPC and Log in Using the HTTP Interface, respectively.
pathstrPath and file name to delete. All attempts to delete multiple files through the use of wildcards fail with a return code of -1 (file does not exist).

Return Codes

  • 0: success
  • -1: file does not exist
  • -10001: invalid token
For a list of error codes not specific to deleteFile, see Global Error Codes.

Response Data

Returns only the codes discussed in Return Codes. Does not return any data structures.

Python Sample Requests

Delete the example1.jpg from the root directory:
Python
1>>> api.deleteFile(token, '/example1.jpg')
20

Move a File

Although the Origin Storage API does not provide a specific method for moving files, you can use the rename method to move a file, specifying a different directory for the newpath parameter.

Python Sample Requests

Move example.txt from the /e directory to the /d directory:
Python
1>>> api.rename(token, '/e/example.txt', '/d/example.txt')
20

List Files

Method name: listFile
Lists files that are direct children of a given path. The method is not recursive and operates only on the given path.

List Files Using Named Parameters

JSON
1{
2  "method": "listFile",
3  "id": 1,
4  "params": {
5    "token": "70f2c2c9-42fc-4021-913a-6487217e19b4",
6    "path": "/",
7    "pageSize": 1,
8    "cookie": 0,
9    "stat": true
10  },
11  "jsonrpc": "2.0"
12}

List Files Using Positional Parameters

Positional parameters must be applied in the same order shown in the named parameters sample. Example:
JSON
1{
2  "method": "listFile",
3  "id": 0,
4  "params": [
5    "ad80c27a-f18c-42a2-9197-feea7631ab3b",
6    "/",
7    1,
8    0,
9    true
10  ],
11  "jsonrpc": "2.0"
12}

Parameter Descriptions

Parameter NameTypeDescription
tokenstrValid token from a call to login (JSON-RPC interface) or /account/login (HTTP interface). See Log In Using JSON-RPC and Log in Using the HTTP Interface, respectively.
pathstrDirectory to list
pageSizeintOptional>

The number of files to return from a call to the method. Must be less than or equal to 10000.

Defaults to 100
cookieuint64Optional

On return, indicates whether additional files can be returned with subsequent calls to the function.

Omit this argument or pass 0 the first time you call the function. For all subsequent calls, pass the cookie value returned from the prior call.

Defaults to 0
statboolOptional

Include file details in output.

Defaults to False

Return Codes

  • 0: success
  • -1: invalid path
  • -11: invalid cookie
  • -12: invalid page size
  • -10001: invalid token
For a list of error codes not specific to listFile, see Global Error Codes.

Response Data

When the stat parameter is set to False, the method returns an object with the following data:
  • code: (int) return code
  • cookie: (uint64) indicates whether additional files can be returned with subsequent calls to the function. Non-zero value: additional files are available. Zero value: no more files are available.
  • list: array of file objects. Data for each object is:
    • name: (str) file name
    • type: (int). Always 2 (file)
The order in which files are returned is non-deterministic. Results are not sorted.
Example:
JSON
1{
2  "code": 0,
3  "cookie": 2,
4  "list": [
5    {
6      "name": "flat-irons.jpg",
7      "type": 2
8    },
9    {
10      "name": "farm-cat.jpg",
11      "type": 2
12    }
13  ]
14}
When the stat parameter is set to True, each file listed includes a stat object with the following data:
  • checksum: (str) file’s SHA-256 hexidecimal digest
  • ctime: (int) creation time in seconds since epoch
  • gid: (int) group ID of user that created the file
  • mimetype: (str) file’s MIME type. Example: text/plain
  • mtime: (int) last modification time in seconds since epoch
  • size: (int) file size
  • uid: (int) ID of user that created the file
Example:
JSON
1{
2  "code": 0,
3  "cookie": 1,
4  "list": [
5    {
6      "stat": {
7        "uid": 12020,
8        "gid": 100,
9        "size": 659819,
10        "checksum": "24a436b8a87462482806667b76ec5a120ae236a721c311a66235ad3cf4073bd4",
11        "ctime": 1423676679,
12        "mimetype": "image/jpeg",
13        "mtime": 1423676671
14      },
15      "name": "flat-irons.jpg",
16      "type": 2
17    }
18  ]
19}

Python Sample Requests

Loop through all files in a directory in chunks of three and print the file names.
Python
1# User-defined variables
2dir = '/'
3pageSize = 3
4

5def printFiles( fileList ):
6  global hasFiles
7  for ( item ) in fileList:
8    hasFiles = True
9    print item['name']
10

11hasFiles = False
12results = api.listFile( token, dir, pageSize, False )
13

14print ('Files in directory "' + dir + '":')
15printFiles( results['list'] )
16cookie = results['cookie']
17

18while ( cookie > 0 ):
19  results = api.listFile( token, dir, pageSize, cookie, False )
20  printFiles( results['list'] )
21  cookie = results['cookie']
22

23if not hasFiles:
24  print ('**No files in directory**')

Set a File’s Content Type

Method name: setContentType
Sets a file’s content type to one of the standard MIME types.
Note the following:
  • If you attempting set content type on a directory, the call seems to succeed (returns 0) but in reality has no effect.
  • To use setContentType on an object, you must belong to the group that owns the object. To determine the group that owns the object, issue a stat call on the object, setting the detail parameter to True. Then look at the gid value from the results of the call. (See [Obtain File or Directory Metadata](Working With Directories and Files Common.htm#Obtain) for information about the stat function.)To determine your group, you must log in using the login function, setting the detail parameter to True. Then look at the gid value from the results of your call to login. If the two gid values match, you will be able to set the file’s content type.

Set Content Type Using Named Parameters

JSON
1{
2  "method": "setContentType",
3  "id": 1,
4  "params": {
5    "token": "12086a82-eed2-4e83-a25b-514a55416b5b",
6    "path": "/a/hi1.txt",
7    "content_type": "text/plain"
8  },
9  "jsonrpc": "2.0"
10}

Set Content Type Using Positional Parameters

Positional parameters must be applied in the same order shown in the named parameters sample. Example:
JSON
1{
2  "method": "setContentType",
3  "id": 0,
4  "params": [
5    "8c4b1dfc-d36d-4070-8221-f969bc040110",
6    "/a/hi1.txt",
7    "text/plain"
8  ],
9  "jsonrpc": "2.0"
10}

Parameter Descriptions

Parameter NameTypeDescription
tokenstrValid token from a call to login (JSON-RPC interface) or /account/login (HTTP interface). See Log In Using JSON-RPC and Log in Using the HTTP Interface, respectively.
pathstrFile whose content type you want to set.
content_typestrContent type such as text/plain. See Content Types.

Return Codes

  • 0: success
  • -1: file does not exist or invalid object type
  • -3: parent path does not exist
  • -6: permission denied. Caller’s uid does not exist or does not have permissions to path.
  • -8: invalid path
  • -33: invalid content type
  • -10001: invalid token
    For a list of error codes not specific to setContentType, see Global Error Codes.

Response Data

Returns only the codes discussed in Return Codes. Does not return any data structures.

Python Sample Requests

Set content type on cloud-storage-icon.png:
Python
1>>> api.setContentType(token, '/dir10/cloud-storage-icon.png', 'image/png')
20

Generate a MediaVaultURL

Method name: mediaVaultUrl
Generates time-limited URLs you can use to download or preview a file. The time limit is enforced through an expiry time. All requests for the file using the URLs are refused when the expiry time has passed. The expiry time relates to the start of the HTTP GET request, so as long as the request is initiated before this time the download will be successful.
For additional information about MediaVault, please see the MediaVault User Guide.

Generate MediaVault URL Using Named Parameters

JSON
1{
2  "method": "mediaVaultUrl",
3  "id": 1,
4  "params": {
5    "token": "d6835f68-7bd4-4a29-9c40-54fbaeeb2444",
6    "path": "/TreesOfEurope/DeciduousTrees.txt",
7    "expiry": 3600
8  },
9  "jsonrpc": "2.0"
10}

Generate MediaVault URL Using Positional Parameters

Positional parameters must be applied in the same order shown in the named parameters sample. Example:
JSON
1{
2  "method": "mediaVaultUrl",
3  "id": 1,
4  "params": [
5    "1ee13c07-1f50-4c05-8f89-d5779e17332b",
6    "/TreesOfEurope/DeciduousTrees.txt",
7    3600
8  ],
9  "jsonrpc": "2.0"
10}

Parameter Descriptions

Parameter NameTypeDescription
tokenstrValid token from a call to login (JSON-RPC interface) or /account/login (HTTP interface). See Log In Using JSON-RPC and Log in Using the HTTP Interface, respectively.
pathstrFile to generate URL.

The path does not have to exist, this is to support generating a URL prior to uploading an object.
expiryintOptional

Download URL expiry for object in seconds.

Must be in the range 1 to 2147483648.

If expiry is 0 or omitted, it defaults to 3600.

Return Codes

  • 0: success
  • -1: internal error
  • -2: path exists and is a directory
  • -8: invalid path
  • -34: invalid expiry
  • -60: service is disabled or unavailable
  • -10001: invalid token

Response Data

The method returns an object with the following data:
  • code: (int) return code
  • download_url:(str) URL to use for downloading the file
  • message: description of code
  • preview_url: (str) URL to use for previewing the file
Example:
JSON
1{
2  "code": 0,
3  "download_url": "http://cs-download.limelight.com/<path to file>",
4  "message": "success",
5  "preview_url": "http://cs-download.limelight.com/<path to file>",
6}

curl Sample Request

Generate MediaVault URLs for the example3.jpg file. This code first calls the ‘login’ method and extracts the token from the output. Next, the code issues the call for the MediaVault URL, passing the extracted token.
1token=$(curl -v -X POST -H 'X-Agile-Username: yourUser' -H 'X-Agile-Password: yourPassword' 'https://[Account name]-l.upload.llnw.net/account/login' 2>&1 | grep X-Agile-Token: | awk -F ': ' '{print $2}' | tr -d '\r')
2curl -v -k^
3

4curl -d '{"jsonrpc": "2.0", "method": "mediaVaultUrl", "params": ["'$token'", "/example3.jpg", 300], "id": 1}' 'https://[Account name]-l.upload.llnw.net/jsonrpc'