The "dir" action (NS4)

Use the "dir" action with an NS4 storage group to list the objects directly within the specified directory (similar to a standard "ls" or "dir" command).

This action lists files, symlinks, and explicit subdirectories that are directly within the specified directory. Additionally, implicit subdirectories are specifically listed, and are labeled with the XML attribute, implicit="true".

A dir action is an advanced form of the stat action. By comparison the actual "stat" action can be used to target a specific directory, file, or symlink to reveal a limited set of information, while the "dir" action is used to target a specific directory.

GET /[CP Code]/[Path] HTTP/1.1
Host: [Domain Prefix]-nsu.akamaihd.net
X-Akamai-ACS-Action: version=1&action=dir&format=xml&[Optional variables]
[Signature Header 1]
[Signature Header 2]
Tip: If you are not concerned about specifically calling out implicit directories, the "list" action offers a different methodology and implicit directories are not specifically called out.

Required variables

Variable values are as follows:

  • [CP Code]: The unique CP Code that represents the root directory in the applicable NetStorage Storage Group.
  • [path]: If applicable, any additional sub-directories, ending with the target directory
Note: Typically, this action must be used to target a directory. If an actual file is included in the [path], an error will be revealed. (An “HTTP 412” will be displayed). The stat action is used to display file information. However, due to the nature of the ObjectStore (NS4) filesystem, there are exceptions to this rule. When this applies, it is discussed here.
  • [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 action header field variables

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

  • prefix=[prefix]: Only list files whose names begins with the specified prefix.
  • start=[value]: Start with the first file in the directory whose name is greater than or equal to this value. This value is appended to the prefix if that field is also included.
  • end=[value]: Do not return any files whose name is greater than this value. Note that the trailing " /" for implicit and explicit directories is included in the comparison against the end value. This value is appended to the “prefix” if that field is also included.
  • max_entries=[#]: List this number of objects at a maximum. Note that the server may choose to 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.
  • slash=both: In the event of duplicate file/symlink and directory names in the same parent, ObjectStore will default to only displaying the file/symlink. Include this optional action header to have both files/symlinks and directories with the same name displayed. To differentiate entries in the response, refer to the file type attribute.
  • 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.