Usage details for "dir"

The API response for this action is in XML format.

The response contains one <file...> tag per entry found in the targeted directory. With a NetStorage file system, an implicit directory displays as a file entry, and it's listed in the response output for this action.

🚧
When interpreting response output from this call, you must support the appropriate XML escaping for object names that include characters such as a quote ( " ) and an ampersand ( & ).

Lexicographical response example the "dir" action

The API results are in lexicographic order for the dir action, listing objects in the specified [path]. Let's assume that you're using this action to target the following "sampledir" [path]:

GET /[CP code]/sampledir HTTP/1.1

1 | <stat directory="/[CP code]/sampledir">  
2 |     <file type="file" name="File2" size="398421" md5="[HASH]" mtime="1524068379"/>  
3 |     <file type="symlink" name="My_symlink.html" target="File1" mtime="1524110333"/>  
4 |     <file type="dir" name="dir1" bytes="19873716" files="6" mtime="1524068415" implicit="true"/>  
5 |     <file type="dir" name="dir2" bytes="3874912" files="1" mtime="1524068422" implicit="true"/>  
6 |     <file type="dir" name="explicitdir1" bytes="0" files="1" mtime="1524068459"/>  
7 |     <file type="dir" name="explicitdir2" bytes="3" files="2" mtime="1524068462"/>
8 |     <file type="file" name="file1" size="532459" md5="[HASH]" mtime="1524068382"/>   
9 | </stat>

Explanation of response results

📘
The line numbers shown in the example above don't appear in the actual output. They are only for reference in the points that follow.

The targeted [path] is listed first in the response.
Objects are listed in "lexicographical" order. As an example of this, notice how a file named "File2" (line 2) is displayed before a directory named "dir1" (line 4).
Objects also include informational details:
- Files and symlinks: This includes the size of the file, the associated md5 hash, and the time the file was last modified (mtime).
- Directories: This includes the total size of all file content in bytes, the number of files in the directory, the last modified date (mtime). Finally, if the directory is implicit it is labeled as such.

How NetStorage uses lexicographic sorting

Lexicographical sorting is the ordering of objects based on the first character that is different. When one is a prefix of the other, the shorter string is "less."

Results are sorted by comparing each character position with numbers displayed before alpha characters. Objects are listed from the specified start [path] in this sort order:

Numbers: Numbers are displayed alphabetically before alpha characters. In this example "10" comes before "2" due to the first character "1" being less than "2".
- Example: 1, 10, 2, 21, 3
Alpha characters: Alphabetic sorting takes case sensitivity into consideration. Capitalized letters sort before lowercase.
- Example: C, D, a, b

You can resume a "dir" listing

If you stop a "dir" listing of a storage group, you can resume it.

A response to this action may contain a large amount of entries. To limit excessive output, you can utilize the max_entries=[#] field in the action header for the call. Subsequently, the Akamai network may enforce a limit, based on various implementation-dependent factors. If the dir listing is not complete, a resume start is returned as the final item in the response output. It will be comprised of the next object in the list, and look similar to the following:

<stat directory="/[CP Code]/dir1/dir2/"> 
    ... [add'l response entries] 
    <file type="file" name="b.log"/> 
    <resume start="c.log">
</stat>

The “resume start” can then be used in a subsequent dir action call to continue the response from where the previous request finished:

How to resume a "dir" listing

Define the Request Path using the same method (GET), and include the full path to the resume start object, minus the actual object (For example, [CP Code]/dir1/dir2/, using the example, above.)
Include the start=[value] field in the action header and set the [value] variable to the object shown at the end of the resume start path. (Perform any necessary XML un-escaping and HTTP URL escaping in the process.)
If you also included the prefix=[prefix] action header in the original request, also include it here, using the same [prefix] value.

GET /[CP Code]/dir1/dir2/link2 HTTP/1.1 
 Host: [Domain Prefix]-nsu.akamaihd.net 
 X-Akamai-ACS-Action: version=1&action=dir&format=xml 
 [Recomputed Signature Headers]

What you should see

As a result, the dir listing will continue from the specified point, similar to the example that follows:

<stat directory="/[CP Code]/dir1/dir2/">
    <file type="symlink" name="[CP Code]/dir1/dir2/c.log"/> 
    <file type="file" name="[CP Code]/dir1/dir2/d.log" size="129444" md5="34e4e082ddbc76424d1e0ff08f485641" mtime="1371132700"/> 
    ... [add'l response entries] 
</stat>

You can include "max-entries=[#]" in a "dir" resume**

Just like an initial call, you can include the max-entries=[#] field in the action header in a resumed dir, to limit resulting output. As a result, a new resume start is returned in the response. It could then be used to continue the dir, using the steps discussed above.

📘
Once a dir is initiated, it must run to fruition. If you anticipate a large number of records in the response, it is recommended that you include the max_entries=[#] field in the action header--both initially, as well as in subsequent “resumes”.

Considerations when using "dir"

Trailing slashes and "dir"

Traditionally used as path separators, the forward slash “/” is supported for use in the names of a directory as well as a file. This is important because it can affect how paths must be input with this action to obtain the desired response.

Trailing slashes in directory names

One or more trailing slashes can be used in a directory name, and not just as a path separator. (They can be used to end a directory name). Therefore, it is important to note the following to properly specify the desired directory as the [Path] variable for this call:

The directory name contains no additional trailing “/”: If a directory in the path does not use any additional trailing “/” in its name, simply include a single “/” to serve as a path separator after the directory.
The directory name contains additional trailing “/”: Include the appropriate number of trailing “/” to properly specify the directory by name, but also include one additional “/” to serve as the path separator. (For example, new// would be input as new///).
The final directory in the path: NetStorage will automatically apply a final “/” in a path to denote that object as a directory. Therefore, the following apply:
- If the final directory name doesn't contain trailing slashes: You can either leave the slash out of the path, in which case NetStorage will apply one as noted; or you can include a single “/”, and NetStorage will acknowledge it as a path separator.
- If the final directory name contains trailing slash(es): If the final directory name includes a single trailing slash in its name (“new/”), you must include an additional slash to denote it as a part of the directory name (“new//"). If the directory includes multiple trailing slashes, include only the specific number of trailing slashes in the title (“new//” would be specified as “new//” — no need to include an additional slash, because NetStorage will recognize the object as a directory).

For example, if you have created a sub-directory named test/, in the root directory /new, this would result in the actual path being /new/test//. You would need to specify this full path — /new/test// as the “[Path]” variable to properly target this directory.

Trailing slashes in file names

Like a directory, a file can exist with one or more trailing slashes in its filename. For example, if you have created a symlink entitled link/, in the root directory /new, a dir action call with new defined as the [path] (“ GET /[CP Code]/new HTTP/1.1”) would reveal the following:

<stat directory="/[CP Code]/new"> 
    ... <file type="dir" name="link" bytes=”0” files="1" implicit=”true” >
</stat>

Since the actual filename ends with a “/,” it is treated as an empty file name within the implicit directory, link. To properly view details on the symlink, its filename needs to be included in the call—GET /[CP Code]/new/link/ HTTP/1.1. (And, you would either include or omit the trailing “/”.) As a result, the response would look as follows:

<stat directory="/[CP Code]/new/link">
    <file type="symlink" name="" bytes=”0” mtime="1260000000" > 
</stat>

Notice that the “name” attribute is empty, because rather than a directory revealing its contents, the actual file — link/ — was the target of the call.

Periods in directory and file names

NetStorage supports path components that start with a period (“.”).

The periods in each are simply considered strings. As long as the client views a filename of “.” or “..” literally, a dir action will recognize any iteration of “.” as part of a directory name.

dir1/dir2/.test/one
dir1/dir2/./one
dir1/dir2/../one

Files and directories with the same name

Files, symlinks, and directories can share the same name in NetStorage storage groups. By default, only the file/symlink will be revealed in the case of a duplicate, unless the &slash=both field is included in the action header.

With this field incorporated, consult the file type attribute in the response to differentiate components.

<stat directory="/[CP Code]/dir1/dir2/"> 
    <file type="symlink" name="bases" mtime="1260000000" /> 
    <file type="dir" name="bases" bytes=”0” files="1" 
</stat>

In the above example, the path dir1/dir2/ is comprised of two entries with the same name, bases. (One is a symbolic link and the other is a directory.)