Listing directory contents

Content Platform Tenant Management Help

Version
9.7.x
File Size
4269 KB
Audience
anonymous
Part Number
MK-95HCPH002-19

You use the HTTP GET method to list the contents of a directory in a namespace. This method does not list old versions of objects.

Access permission

To list the contents of a directory, you need browse permission.

Request header

GET /rest/directory?deleted=true HTTP/1.1
Parameter Required Description
directory Yes Folder name.
delete No

By default, a directory list does not include deleted objects or directories. If the namespace supports versioning, you can include deleted objects and directories in the list. To do this, specify this URL query parameter:

deleted=true

You can also specify deleted=false, which results in the default behavior.

Also specify the deleted=true parameter to list the contents of a deleted directory (which can contain only deleted objects and directories).

mostRecentDirTimes No

Either:

  • false, the default, which shows the change time returned for each subdirectory in a directory list is the time the subdirectory was created or, if the subdirectory is a deleted directory, the time it was deleted. .
  • true, which shows change times that are the most recent of
    • The time the subdirectory was created
    • The time the subdirectory was deleted
    • The time an object was most recently added to the subdirectory
    • The time an object was most recently deleted from the subdirectory

Response headers

The list below describes the request-specific response header for this operation.

X-HCP-Type
The object entity type.
X-HCP-ChangeTimeMilliseconds
The change time for the directory, in milliseconds since January 1, 1970, at 00:00:00 UTC, followed by an integer that is unique for the change time. For example: 1336483100178.00.
The change time for a directory is the most recent of:
  • The time the directory was created
  • The time the directory was deleted
  • The time an object was added to the directory
  • The time an object was deleted from the directory
X-HCP-ChangeTimeString
The change time for the object in this format:
yyyy-MM-ddThh:mm:ssZ
In this format, Z represents the offset from UTC and is specified as:
(+|-)hhmm
For example, 2020-09-18T09:18:20-0400 represents the start of the 20th second into 9:18 AM, September 18, 2020, EDT.
X-HCP-SymlinkTarget
The path to the target object as specified when the symbolic link was created.
This header is returned only if the URL specifies a symbolic link to an object.
If this header is returned, the X-HCP-ACL value is always false.

Response body

The body of the HTTP response consists of XML that lists the contents of the requested directory, including metadata for the objects the directory contains. It lists only the immediate directory contents, not the contents of any subdirectories.

Element Attribute Description
directory path Location of the directory.
directory utf8path UTF-8 compatible location of the directory.
directory parentDir Location of the parent directory.
directory utf8ParentDir UTF-8 compatible location of the parent directory.
directory dirDeleted Boolean value. Indicates whether the directory is currently deleted.
directory showDeleted Boolean value. Indicates whether the directory includes delete records.
directory namespaceName Name of the namespace where the directory resides.
directory utf8NamespaceName UTF-8 compatible name of the namespace where the directory resides.
directory changeTimeMilliseconds Seconds after 1 January 1970 that the object was either modified or deleted.
directory changeTimeString Change date and time. In ISO 8601 format, which is the time in the time zone of the HCP system followed by the hour and minute offset between local time and UTC.
entry urlName URL of the subdirectory, symbolic link, or object.
entry utf8Name UTF-8 compatible name of the subdirectory, symbolic link, or object.
entry type

Subdirectories have the type directory.

Symbolic links have the type symlink.

All other objects have the type object.

entry changeTimeMilliseconds Seconds after 1 January 1970 that the object was either modified or deleted.
entry changeTimeString Change date and time. In ISO 8601 format, which is the time in the time zone of the HCP system followed by the hour and minute offset between local time and UTC.
entry state Status is either created or deleted. Specifies whether the version contains data or is a marker indicating that the object was deleted.
entry etag Etags for the object.
entry hashScheme Type of hash algorithm, such as MD5. Not returned for multipart objects.
entry hash Hash value. Not returned for multipart objects.
entry retention Retention in seconds after 1 January 1970
entry retentionString Retention day and time value. In the time zone of the HCP system.
entry retentionClass Retention class name.
entry ingestTime Seconds after 1 January 1970 that the object was either created or deleted.
entry ingestTimeString Ingested date and time. In the time zone of the HCP system.
entry hold Boolean. Whether or not the object has a hold.
entry shred Boolean. Whether or not the object is to be shredded after it is deleted.
entry index Boolean. Whether or not the object is to be indexed.
entry customMetadata Boolean. Whether or not the object has custom metadata.
entry customMetadataAnnotations Annotations associated with the object. Delimited by semicolons.
entry replicated Boolean. Whether or not the object is replicated.
entry owner User name of the owner of the object. If there is no owner listed, the value is nobody.
entry domain Active Directory domain
entry hasAcl Boolean. Whether or not ACL is present for the object.
entry state Status is either created or deleted. Specifies whether the version contains data or is a marker indicating that the object was deleted.

Status codes

The table below describes the HTTP status codes that have specific meaning for this request.

Code Meaning Description
200 OK HCP successfully retrieved the directory listing. This code is also returned if the URL specified an object and HCP successfully retrieved the object.
404 Not Found

One of:

  • HCP could not find a directory, object, or version at the specified URL. The specified object or version does not exist, or the request specified the current version of an object that has been deleted.
  • Any component of the URL except for the last component in the path is a symbolic link to a directory.

Example: Listing the contents of a directory that includes deleted objects

Here’s a sample HTTP GET request that lists all the contents, including any deleted objects or subdirectories, of a directory named quarterly_rpts in a namespace that supports versioning.

Request with curl command line

curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts?deleted=true"
    > quarterly_rpts.xml

Request in Python using PycURL

import pycurl
filehandle = open("quarterly_rpts.xml", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /rest/quarterly_rpts?deleted=true")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.WRITEFUNCTION, filehandle.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()

Request headers

GET /rest/quarterly_rpts?deleted=true HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1335036864
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: text/xml
X-HCP-Type: directory
X-HCP-ChangeTimeMilliseconds: 1353420657688.00
X-HCP-ChangeTimeString: 2012-11-20T09:10:57-0500
Content-Length: 577

Response body

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/static/xsl/ns-directory.xsl"?>
<directory xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="/static/xsd/ns-directory.xsd"
    path="/rest/quarterly_rpts"
    utf8Path="/rest/quarterly_rpts"
    parentDir="/rest">
    utf8ParentDir="/rest"
    dirDeleted="false"
    showDeleted="true"
    namespaceName="finance"
    utf8NamespaceName="finance">
    changeTimeMilliseconds="1326336965436"
    changeTimeString="2012-01-11T09:56:05-0500"

    <entry urlName="Q4_2011.ppt"
         utf8Name="Q4_2011.ppt"
         type="object"
         size="671744"
         hashScheme="SHA-256"
         hash="42C605FBFFCD7CEAC36BE62F294374F94503D1DC1793736EF367..."
         retention="0"
         retentionString="Deletion Allowed"
         retentionClass=""
         ingestTime="1326898187"
         ingestTimeString="1/18/2012 2:49PM"
         hold="false"
         shred="false"
         dpl="2"
         index="true"
         customMetadata="false"
         customMetadataAnnotations=""
         version="80238375537921"
         replicated="false"
         changeTimeMilliseconds="1326898187533.00"
         changeTimeString="2012-01-18T14:49:47-0400"
         owner="lgreen"
         domain=""
         hasAcl="false"
         state="created"
    />
    <entry urlName="obsolete"
         utf8Name="obsolete"
         type="directory"
         changeTimeMilliseconds="1331847677748.00"
         changeTimeString="2012-03-15T17:41:17-0400"
         state="deleted"
    />
    <entry urlName="Q1_2012.ppt"
         utf8Name="Q1_2012.ppt"
         type="object"
         size="678400"
         hashScheme="SHA-256"
         hash="E830B86212A66A792A79D58BB185EE63A4FADA76BB8A1C257C01..."
         retention="0"
         retentionString="Deletion Allowed"
         retentionClass=""
         ingestTime="1334847117"
         ingestTimeString="4/19/2012 9:51AM"
         hold="false"
         shred="false"
         dpl="2"
         index="true"
         customMetadata="false"
         customMetadataAnnotations=""
         version="80238376132993"
         replicated="false"
       changeTimeMilliseconds="1334847117598.00"
         changeTimeString="2012-04-19T09:51:57-0400"
         owner="lgreen"
         domain=""
         hasAcl="false"
         state="created"
    />
</directory>

Notice that the obsolete directory was deleted. It does not appear in a directory listing if the URL does not include the deleted=true parameter.