The "list" action (NS4)

You can use the "list" action to return a lexicographical list of all objects within the specified CP code, recursing into subdirectories as they are encountered.

Files in parent directories appear before, between or after the subdirectories are recursed. The order is ASCII based. Objects inside implicit directories are listed, but implicit directories are not listed separately. You can optionally restrict the listing to any arbitrary range of object names. If you want the contents of a specific directory without recursiveness, see the "dir" action.

GET /[CP Code]/[path]/ HTTP/1.1 
Host: [Domain Prefix]-nsu.akamaihd.net 
X-Akamai-ACS-Action: version=1&action=list&format=xml[Optional variables]
[Signature Header 1]
[Signature Header 2]

Required variables

Required variable values are as follows:

  • [CP code]: The unique CP code that represents the root directory in the applicable NetStorage storagegGroup.
  • [Domain Prefix]: This is the unique domain prefix set up for the storage group during its creation. It can be viewed in the NetStorage Groups UI in Control Center.
  • [Signature Header 1] and [Signature Header 2]: Applicable signature headers.

Optional variables

  • [path]: The optional path from where the lexicographical listing will begin. If the path you specify does not exist, or is an empty directory, an HTTP 404 “Not Found” error is returned.
CAUTION: This action guarantees that all objects that exist during the full "list" process are returned exactly once, but objects that are uploaded and/or deleted during the listing process may or may not be returned.

Additional considerations are as follows:

  • If used without optional parameters, the list action reports all objects from the CP code root and subdirectories lexicographically.
  • The server may reduce the response list to prevent excessively large object counts even if “max_entries” is not, specified.
  • If the CP code and an additional path you specify does not exist, or is an empty directory, an HTTP 404 “Not Found” error is returned. Alternatively, the "dir" action would return the directory name in the result.

Optional action header field variables

Along with the standard action header content, the following optional fields can be included. Each must be appended to the end of the header, prefaced by an ampersand (“&”).

  • max_entries=[#]: List this number of objects to a maximum. Note that the server may further reduce this value or apply a limit to excessively large object counts even if “max_entries” is not specified. A “resume start” entry will be revealed at the end of the response, allowing you to continue the listing, if desired.
  • end=/[CP Code]/[path]0: Include this with a complete path to the last object to be returned in the list response. All other objects that exist after the noted path are left out of the response. The "0" character exists in place of the trailing slash to accommodate NS4 directory logic. (As a result, the list will display everything up to, and including the last object in the path—and possibly a path named "[path]0" if one exists.)
  • encoding=[applicable XML encoding type]: ObjectStore (NS4) supports a wider range of XML encodings for use in this action's response. Include this field to define the desired type.
  • mtime_all=yes: Include this parameter to include the modification time for explicit directories and symbolic links. Symbolic links will also include the target.
     <file type="dir" name="2000/example/" mtime="1554918048"/>
     <file type="symlink" name="2000/example/badlink" target="foo" mtime="1554918053"/>
     <file type="file" name="2000/example/passwd" size="2476" md5="[hash]" mtime="1555004086"/>
Note: If you target a large directory, we recommend that you include the max_entries=[#] variable to control response output. If you do not, the action will continue to display all results until it reaches the end of the tree, optional end path or server limit (whichever comes first.) The server may choose to reduce the response list to prevent excessively large object counts even if “max_entries” is not specified.

Explicit vs. Implicit directories and this action

Implicit directories are not listed as directories. They are included as part of the filename. So, they are revealed at the same level of the response as standalone files that exist in the same directory. An example of this is shown in the Lexicographical sorting with the "list" action topic.

The response to the following directory structure will appear as follows:

  • Explicit: /root/explicit1/explicit2/
  • Implicit: /root/explicit1/implicit1/
[/root files and symlinks]
/explicit1
[/explicit1 files and symlinks]
/explicit1/explicit2
[/explicit1/explicit2 files and symlinks]
[/explicit1/implicit1/file2.ext files and symlinks]
Note: If you prefer implicit directories called out as actual directory entries in a response (rather than included as file entries), use the "dir" action.