Edgio
Control Portal

Working with Methods Common to Files and Directories

The Origin Storage API provides methods that apply to both files and directories, such as renaming a file or directory. APIs for working with existing files are available in the JSON-RPC interface only.

List Files and Directories

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

Using Named Parameters

JSON
1{
2  "method": "listPath",
3  "id": 1,
4  "params": {
5    "token": "f03efb6a-c63c-4046-9bd9-d1cd8c36c10b",
6    "path": "/a",
7    "pageSize": 1,
8    "cookie": "",
9    "stat": true
10  },
11  "jsonrpc": "2.0"
12}

Using Positional Parameters

Positional parameters must be applied in the same order shown in the named parameters example.
JSON
1{
2  "method": "listPath",
3  "id": 0,
4  "params": [
5    "3984d225-286e-41b6-811a-99fcea4dd411",
6    "/a",
7    1,
8    "",
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 for which you want to list files and directories.
pageSizeintOptional

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

Defaults to 100.
cookiestrOn return, indicates whether additional files or directories can be returned with subsequent calls to the function.

Pass an empty string the first time you call the function. For all subsequent calls, pass the cookie value returned from the prior call. After you have returned all files and directories, the returned cookie value is null.

Defaults null
statboolOptional

Indicates whether to include file details in output.

Defaults to False

Return Codes

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

Response Data

On success returns an object with the following data:
  • code: (int) return code. See Return Codes for specific values.
  • cookie: (str) base64-encoded string indicating whether additional files or directories can be returned with subsequent calls to the function. Non-null value: additional files or directories are available. Null value: no more files or directories are available.
  • dirs: an array of directory objects returned. The exact attributes in each object depends on whether you pass True or False for the stat parameter.
  • files: an array of directory objects returned. The exact attributes in each object depends on whether you pass True or False for the stat parameter.
When the stat parameter is set to False, the method returns the following data for each directory or file in the dirs and files lists respectively:
  • name: directory or file name
Example:
JSON
1{
2  "code": 0,
3  "cookie": "AAAAAAAAAAEAAAAAAAAAAQ\u003d\u003d",
4  "dirs": [
5    {
6      "name": "steve"
7    }
8  ],
9  "files": [
10    {
11      "name": "flat-irons.jpg"
12    }
13  ]
14}
When the stat parameter is set to True, the method returns the following additional data:
  • checksum: (str) file’s SHA-256 hexidecimal digest (files only)
  • ctime: (int) creation time in seconds since epoch
  • gid: (int) group ID of user that created the file or directory
  • mimetype: (str) file’s MIME type. Example: text/plain (files only)
  • mtime: (int) last modification time in seconds since epoch
  • size: (int) file size in bytes (files only)
  • uid: (int) ID of user that created the file or directory
Example:
JSON
1{
2  "code": 0,
3  "cookie": "AAAAAAAAAAEAAAAAAAAAAQ\u003d\u003d",
4  "dirs": [
5    {
6      "uid": 12020,
7      "gid": 100,
8      "name": "steve",
9      "ctime": 1423258489,
10      "mtime": 1423258489
11    }
12  ],
13  "files": [
14    {
15      "uid": 12020,
16      "gid": 100,
17      "size": 659819,
18      "name": "flat-irons.jpg",
19      "checksum": "24a436b8a87462482806667b76ec5a120ae236a721c311a66235ad3cf4073bd4",
20      "ctime": 1423676679,
21      "mimetype": "image/jpeg",
22      "mtime": 1423676671
23    }
24  ]
25}
When you call the method on an empty directory, or after you have returned all files and directories and you call the method again, it returns the following:
JSON
1{
2  "code": 0,
3  "cookie": null,
4  "dirs": [],
5  "files": []
6}
When you call the method on a directory with a file but no directory, the method returns the following:
JSON
1{
2  "code": 0,
3  "cookie": "AAAAAAAAAAAAAAAAAAAAAQ==",
4  "dirs": [],
5  "files": [
6    {
7      "name": "text-file.txt"
8    }
9  ]
10}
Similarly, when you call the method on a directory with a sub-directory but no files, the method returns the following:
JSON
1{
2  "code": 0,
3  "cookie": "AAAAAAAAAAAAAAAAAAAAAQ==",
4  "dirs": [
5    {
6      "name": "sub-dir"
7    }
8  "files": [],
9  ]
10}
On failure returns an object like the following, with code set to the appropriate value described in Return Codes:
JSON
1{
2  "code": -1
3}

Python Sample Requests

Obtain and display formatted information about a directory specified by the variable dirName. Details include stat data.
Python
1import jsonrpclib, time
2

3class StatError(RuntimeError):
4  def __init__(self, arg):
5    self.args = arg
6

7class ListPathError(RuntimeError):
8  def __init__(self, arg):
9    self.args = arg
10

11# User-Defined Variables
12dirName = '/'
13pageSize = 30
14

15#Variables maintained by the application.
16cookie = ''
17numFiles = 0
18numDirs = 0
19totalBytes = 0
20

21try:
22

23  ##################################################
24  # Retrieve directories and files in the directory.
25  ##################################################
26  while cookie is not None:
27    res = api.listPath(token, dirName, pageSize, cookie, True)
28    code = res['code']
29    if code !=0:
30      msg = 'Error issuing listPath command on directory: ' + dirName
31      msg += '\n  Return code: ' + str( code )
32      msg += '\n  See API documentation for details.'
33      raise ListPathError( msg )
34

35    numDirs  += len(res['dirs'])
36    numFiles += len(res['files'])
37    files = res['files']
38    for f in files:
39      totalBytes += f['size']
40    cookie = res['cookie']
41

42  ######################################
43  # Get the directory's ctime and mtime.
44  ######################################
45  myStat = api.stat(token, dirName, True)
46  code = myStat['code']
47  if code != 0:
48    msg = 'Error issuing stat command on directory: ' + dirName
49    msg += '\nReturn code: ' + str( code ) + '\nSee API documentation for details.'
50    raise StatError( msg )
51

52  creationTime = time.strftime('%Y-%m-%d %H:%M:%S', time.localtime( myStat['ctime'] ))
53  modificationTime = time.strftime('%Y-%m-%d %H:%M:%S', time.localtime( myStat['mtime'] ))
54

55  ################################
56  # Display directory information.
57  ################################
58  hdrSep    = '================================================='
59  detailSep = '-------------------------------------------------'
60

61  hdr = 'Information for Directory "' + dirName + '"'
62

63  thisHdrSep = hdrSep
64  if len( hdr ) > 49:
65    while len( thisHdrSep ) < len( hdr ):
66      thisHdrSep += thisHdrSep
67

68  thisHdrSep = thisHdrSep[0: len(hdr)]
69

70  print (thisHdrSep)
71  print (hdr)
72  print (thisHdrSep)
73  print ('Total Directories:            ' + str( numDirs )
74  print (detailSep
75  print ('Total Files:                  ' + str( numFiles )
76  print (detailSep
77  print ('Total Size All Files (bytes): ' + str( totalBytes )
78  print (detailSep
79  print ('Directory Creation time:      ' + creationTime)
80  print (detailSep)
81  print ('Directory Modification time:  ' + modificationTime)
82  print (detailSep)
83

84except ListPathError,e:
85  print (''.join( e.args ) )
86

87except StatError,e:
88  print (''.join( e.args ) )
89

90finally:
91  print ('\nLogging out...\n')
92  res = api.logout(token)
93  print ('Logout results: ' + str( res ) )
If you are interested in seeing the values in a cookie, use code like the following:
1>>> import base64, struct
2>>> cookie = api.listPath(token, '/', 2, None, True)['cookie']
3>>> (dcookie, fcookie) = struct.unpack(">QQ", base64.b64decode(cookie))
4>>> # View number of directories returned
5>>> dcookie
62
7>>> # View number of files returned
8>>> fcookie
92

Obtain File or Directory Metadata

Method name: stat
Obtains meta data such as creation time and last modified time for a specified file or directory.

Using Named Parameters

JSON
1{
2  "method": "stat",
3  "id": 1,
4  "params": {
5    "token": "46c939fa-7ab7-4ea6-b305-494d94c66e3a",
6    "path": "/a/hi1.txt",
7    "detail": true
8  },
9  "jsonrpc": "2.0"
10}

Using Positional Parameters

Positional parameters must be applied in the same order shown in the named parameters example.
JSON
1{
2  "method": "stat",
3  "id": 1,
4  "params": [
5    "46c939fa-7ab7-4ea6-b305-494d94c66e3a",
6    "/a/hi1.txt",
7    true
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.
pathstrDirectory or file for which to provide details.
detailboolOptional

Indicates whether to Include file details in output.

Defaults to False

Return Codes

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

Response Data

When the detail parameter is set to False, the method returns an object with the following data:
  • code: (int) return code
  • ctime: (int) creation time in seconds since epoch
  • mtime: (int) last modification time in seconds since epoch
  • size: (int) file size in bytes (files only)
  • type: (int) identifies the path type: 1 = directory, 2 = file
Example:
JSON
1{
2  "code": 0,
3  "size": 698666,
4  "ctime": 1434579443,
5  "mtime": 1450392160,
6  "type": 2
7}
When the detail parameter is set to True, the following additional data is returned:
  • checksum: (str) file’s SHA-256 hexadecimal digest. Empty string for directories
  • gid: (int) group ID of user that created the directory
  • mimetype: (str) file’s MIME type (files only)
  • uid: (int) ID of user that created the file or directory
Example:
JSON
1{
2  "uid": 12020,
3  "code": 0,
4  "gid": 100,
5  "size": 698666,
6  "checksum": "46cb29d05b447367e343143450ae1ca8cbe0080af225a8310c832be4ba64a096",
7  "ctime": 1434579443,
8  "mimetype": "image/jpeg",
9  "mtime": 1450392160,
10  "type": 2
11}
On failure returns the following object with code set to the appropriate value described in Return Codes:
JSON
1{
2  "uid": 0,
3  "code": -1,
4  "gid": 0,
5  "checksum": ""
6}

Python Sample Requests

View meta data for a directory, including details. Note the empty string value for checksum.
Python
1api.stat(token, '/', True)
2{
3  "uid": 12020,
4  "code": 0,
5  "gid": 100,
6  "checksum": "",
7  "ctime": 1395777680,
8  "mtime": 1395777680,
9  "type": 1
10}
View meta data for the /example2.jpg file, including details:
api.stat(token, '/example2.jpg', True)
Python
1{
2  "uid": 12020,
3  "code": 0,
4  "gid": 100,
5  "size": 4662,
6  "checksum": "71ad472cbd384ef2a8a5f6f7bcc4d538fe22db162ed087548cda736eef9eb720",
7  "ctime": 1433972816,
8  "mimetype": "application/octet-stream",
9  "mtime": 1431079057,
10  "type": 2
11}

Rename a File or Directory

Method name: rename
Renames a file or directory. Note that you can use this method to move a file by specifying a different parent path in the newPath argument. Similarly, you can move a directory (if it is empty) to another parent directory.
When you rename a file or directory such that it gets moved to a new directory, the system sets the mtime (last modified time) of the old and new parent directories to the current system time.
When you rename a file or directory such that it stays in its current directory, the system sets the directory’s mtime to the current system time.
Although Edgio provides APIs for deleting and renaming a directory, you can do so only if the directory contains no files or sub-directories. This is because the required background processes, such as re-applying policies and pushing maps out to Bricks, could potentially have a significant impact on the Origin Storage platform, causing latency in other operations.
If you are having trouble deleting or managing content with the existing supported management tools or via the API, please contact your account manager who will engage the Edgio Advanced Services team to work with you to achieve the desired results (additional charges may apply).

Using Named Parameters

JSON
1{
2  "method": "rename",
3  "id": 3,
4  "params": {
5    "token": "6a1a559c-ae50-4f95-b270-b2dc8519b8fd",
6    "oldpath": "/OldName.txt",
7    "newpath": "/NewName.txt"
8  },
9  "jsonrpc": "2.0"
10}

Using Positional Parameters

Positional parameters must be applied in the same order shown in the named parameters example.
JSON
1{
2  "method": "rename",
3  "id": 2,
4  "params": [
5    "cf725651-cfd0-43a5-8c52-5e113fe61bd2",
6    "/OldName.txt",
7    "/NewName.txt"
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.
oldpathstrExisting file or directory name, including full path
newpathstrNew file or directory name, including full path
Note the following:
  • When renaming a file you must include the full path in the argument to newpath. Arguments to newpath that do not include a full path will be created in the root directory.
  • You cannot rename a directory that has files or sub-directories.
  • You cannot rename a file or directory to an existing name in an attempt to over-write the directory or file.

Return Codes

  • 0: success
  • -1: oldpath not found or attempt to rename a file or directory to its current name
  • -2: newpath already exists
  • -3: newpath parent directory does not exist
  • -6: permission denied. Caller’s uid does not exist or does not have permissions to oldpath.
  • -7: operation not supported. Directory contains files or directories.
  • -10001: invalid token
For a list of error codes not specific to rename, see Global Error Codes.

Response Data

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

Python Sample Requests

Rename the
Python
1>>> api.rename(token, '/auto1.jpg', '/auto3.jpg')
20
Rename the floral-items directory to floral-accessories:
Python
1>>> api.rename(token, '/floral-items', '/floral-accessories')
20

Change a File or Directory Last Modification Time

Method name: setMTime
Changes a file’s or directory’s last modification time.

Using Named Parameters

JSON
1{
2  "method": "setMTime",
3  "id": 1,
4  "params": {
5    "token": "d7320fa4-fd5b-4a4e-a1f9-187143f72d90",
6    "path": "/a/hi1.txt",
7    "mtime": 1461885068
8  },
9  "jsonrpc": "2.0"
10}

Using Positional Parameters

Positional parameters must be applied in the same order shown in the named parameters example.
JSON
1{
2  "method": "setMTime",
3  "id": 0,
4  "params": [
5    "bca3af0b-f417-4131-b28d-3ca4e35fa144",
6    "/a/hi1.txt",
7    1461942652
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 or directory’s whose last modification time you want to change
mtimeintNew modification time in seconds since epoch

Return Codes

  • 0: success
  • -1: file/directory does not exist or you passed an invalid object type
  • -5: cannot acquire lock
  • -8: invalid path
  • -27: invalid mtime
  • -10001: invalid token
For a list of error codes not specific to setMTime, see Global Error Codes.

Response Data

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

Python Sample Requests

Change a file’s modification time:
Python
1>>> api.setMTime(token, '/auto.jpg', 1450392160)
20
Change a directory’s modification time:
Python
1>>> api.setMTime(token, '/picture', 1450392160)
20