Listing directory contents

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
ParameterRequiredDescription
directoryYesFolder name.
deleteNo

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).

mostRecentDirTimesNo

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.

ElementAttributeDescription
directorypathLocation of the directory.
directoryutf8pathUTF-8 compatible location of the directory.
directoryparentDirLocation of the parent directory.
directoryutf8ParentDirUTF-8 compatible location of the parent directory.
directorydirDeletedBoolean value. Indicates whether the directory is currently deleted.
directoryshowDeletedBoolean value. Indicates whether the directory includes delete markers.
directorynamespaceNameName of the namespace where the directory resides.
directoryutf8NamespaceNameUTF-8 compatible name of the namespace where the directory resides.
directorychangeTimeMillisecondsSeconds after 1 January 1970 that the object was either modified or deleted.
directorychangeTimeStringChange 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.
entryurlNameURL of the subdirectory, symbolic link, or object.
entryutf8NameUTF-8 compatible name of the subdirectory, symbolic link, or object.
entrytype

Subdirectories have the type directory.

Symbolic links have the type symlink.

All other objects have the type object.

entrychangeTimeMillisecondsSeconds after 1 January 1970 that the object was either modified or deleted.
entrychangeTimeStringChange 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.
entrystateStatus is either created or deleted. Specifies whether the version contains data or is a marker indicating that the object was deleted.
entryetagEtags for the object.
entryhashSchemeType of hash algorithm, such as MD5. Not returned for multipart objects.
entryhashHash value. Not returned for multipart objects.
entryretentionRetention in seconds after 1 January 1970
entryretentionStringRetention day and time value. In the time zone of the HCP system.
entryretentionClassRetention class name.
entryingestTimeSeconds after 1 January 1970 that the object was either created or deleted.
entryingestTimeStringIngested date and time. In the time zone of the HCP system.
entryholdBoolean. Whether or not the object has a hold.
entryshredBoolean. Whether or not the object is to be shredded after it is deleted.
entryindexBoolean. Whether or not the object is to be indexed.
entrycustomMetadataBoolean. Whether or not the object has custom metadata.
entrycustomMetadataAnnotationsAnnotations associated with the object. Delimited by semicolons.
entryreplicatedBoolean. Whether or not the object is replicated.
entryownerUser name of the owner of the object. If there is no owner listed, the value is nobody.
entrydomainActive Directory domain
entryhasAclBoolean. Whether or not ACL is present for the object.
entrystateStatus is either created or deleted. Specifies whether the version contains data or is a marker indicating that the object was deleted.

Return codes

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

CodeMeaningDescription
200OKHCP successfully retrieved the directory listing. This code is also returned if the URL specified an object and HCP successfully retrieved the object.
404Not 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.