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
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 Also specify the |
mostRecentDirTimes | No |
Either:
|
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 alwaysfalse
.
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 markers. |
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 Symbolic links have the type All other objects have the type |
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. |
Return codes
The table below describes the HTTP return 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:
|
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.