Listing object versions

While versioning is enabled, you use the HTTP GET method to list the versions of an object. By default, the response body contains an XML listing that includes the current version and old versions that haven’t been pruned. It does not include versions that have been deleted. However, you can choose to include delete markers in the list.

If versioning is disabled, even if it was enabled in the past, HCP returns an HTTP 400 (Bad Request) error code in response to a request to list object versions. However, if versioning is then reenabled, HCP returns information about all old versions that have not been pruned.

Access permission

To list object versions, you need browse permission.

Request header

GET /rest/directory/file?version=list&deleted=true HTTP/1.1

The GET request to list object versions has these elements:

  • If you’re accessing the namespace as an authenticated user, an Authorization header.
  • The URL of the object.
  • A version=list URL query parameter.

If you specify a condition, the HCP returns a version list only if all versions of the object meet the specified condition.

ParameterRequiredDescription
directoryYesFolder name.
fileYesName of the file, including file extension.
versionYesUse the value list.
deletedNo

By default, the GET request to retrieve object versions does not include delete markers. To retrieve a listing that includes delete marker, specify this URL query parameter:

deleted=true

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

Response header

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

  • 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 to a GET request to list object versions contains an XML document listing the versions, in this format:

ElementAttributeDescription
versionspathPath to the object.
versionsutf8pathUTF-8 compatible path to the object.
versionsparentDirParent directory of the object.
versionsutf8parentDirUTF-8 compatible path to the paretn directory of the object.
versionsdeletedBoolean value. Indicates whether the object is currently deleted.
versionsshowDeletedBoolean value. Indicates whether the list includes delete markers.
versionsnamespaceNameName of the namespace where the object resides.
versionsutf8NamespaceNameUTF-8 compatible name of the namespace where the object resides.
entryurlnameURL of the object
entryutf8NameUTF-8 compatible name of the object.
entrytypeType of object. Default value is object.
entrysizeSize of the object in bytes.
entryhashSchemeType of hash algorithm, such as MD5.
entryhashHas value.
entryretentionRetention in seconds after 1 January 1970
entryretentionStringRetention day and time value
entryretentionClassRetention class name.
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.
entryversionVersion ID of the object.
entryingestTimeSeconds after 1 January 1970 that the object was either created or deleted.
entryingestTimeStringIngested date and time.
entrychangeTimeMillisecondsSeconds after 1 January 1970 that the object was either modified or deleted.
entrychangeTimeStringChange date and time.

If the directory that contains the object contained at some time a subdirectory with the same name as the object, the results of a version list request that includes delete markers shows delete markers for both the object and the directory.

For example, assume you do the following:

  1. Create a maintenance subdirectory of the departments directory.
  2. Delete the maintenance directory.
  3. Save a maintenance object in the departments directory.

In this case, a version listing for the maintenance entry that includes delete markers shows these items:

  • An entry, with a version ID, for the deleted maintenance directory
  • Entries for all versions of the maintenance object, including any delete marker entries for the object

Version list entries for deleted directories look like this:

<entry urlname="object-name"
    utf8Name="utf8-object-name"
    type="directory"
    state="deleted"
    version=version-id"
    ingestTime="ingested-seconds-after-1/1/1970"
    ingestTimeString="ingested-datetime"
    changeTimeMilliseconds="change-millseconds-after-1/1/1970.unique-integer
    changeTimeString="yyyy-MM-ddThh:mm:ssZ"
/>

Return codes

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

CodeMeaningDescription
200OKHCP successfully returned the version list.
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 versions of an object

Here’s a sample HTTP GET request that saves an XML listing of the versions of an object named Q1_2012.ppt located in the quarterly_rpts directory. The object has three versions: the original version that was ingested, a delete marker, and a version that was ingested after the original version was deleted. The request asks for all versions, including delete markers.

Request with curl command line

curl -i -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/
    Q1_2012.ppt?version=list&deleted=true" > Q1_2012-versions.xml

Request in Python using PycURL

import pycurl
filehandle = open("Q1_2012-versions.xml", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \
  quarterly_rpts/Q1_2012.ppt?version=list&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)
filehandle.close()
curl.close()

Request headers

GET /rest/quarterly_rpts/Q1_2012.ppt?version=list&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: 1334915508
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: text/xml
Content-Length: 2080

Response body

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/static/xsl/ns-versions.xsl"?>
<versions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="/static/xsd/ns-versions.xsd"
        path="/rest/quarterly_rpts/Q1_2012.ppt"
        utf8path="/rest/quarterly_rpts/Q1_2012.ppt"
        parentDir="/rest/quarterly_rpts">
         utf8ParentDir="/rest/quarterly_rpts">
         deleted="false"
         showDeleted="true"
        namespaceName="finance"
         utf8NamespaceName="finance">
    <entry urlName="Q1_2012.ppt"
             utf8Name="Q1_2012.ppt"
             type="object"
             size="678400"
             hashScheme="SHA-256"
             hash="42C605FBFFCD7CEAC36BE62F294374F94503D1DC1793736EF..."
             retention="0"
             retentionString="Deletion Allowed"
             retentionClass=""
             hold="false"
             shred="false"
             dpl="2"
             index="true"
             customMetadata="false"
             customMetadataAnnotations=""
             replicated="false"
             owner="lgreen"
             domain=""
             hasAcl="false"
             state="created"
             version="80232488492929"
             ingestTime="1334829108"
             X-HCP-VersionCreateTimeMilliseconds="1494355864623"
             ingestTimeString="4/19/2012 9:51AM"
             changeTimeMilliseconds="1335347627362.00"
             changeTimeString="2012-04-25T09:53:47-0400"
    />
    <entry urlName="Q1_2012.ppt"
             utf8Name="Q1_2012.ppt"
             type="object"
             size="678400"
             hashScheme="SHA-256"
             hash="36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960B19..."
             retention="0"
             retentionString="Deletion Allowed"
             retentionClass=""
             hold="false"
             shred="false"
             dpl="2"
             index="true"
             customMetadata="false"
             customMetadataAnnotations=""
             replicated="false"
             owner="lgreen"
             domain=""
             hasAcl="false"
             state="deleted"
             version="80232488876481"
             ingestTime="1334829108"
             X-HCP-VersionCreateTimeMilliseconds="1494355864623"
             ingestTimeString="4/19/2012 9:51AM"
             changeTimeMilliseconds="1335607118753.00"
             changeTimeString="2011-04-28T09:58:38-0400"
    />
    <entry urlName="Q1_2012.ppt"
             utf8Name="Q1_2012.ppt"
             type="object"
             size="785690"
             hashScheme="SHA-256"
             hash="36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960B19..."
             retention="0"
             retentionString="Deletion Allowed"
             retentionClass=""
             hold="false"
             shred="false"
             dpl="2"
             index="true"
             customMetadata="false"
             customMetadataAnnotations=""
             replicated="false"
             owner="lgreen"
             domain=""
             hasAcl="false"
             state="created"
             version="80232489767169"
             ingestTime="1335613062"
             X-HCP-VersionCreateTimeMilliseconds="1494355864623"
             ingestTimeString="4/28/2012 11:37AM"
             changeTimeMilliseconds="1335627338110.00"
             changeTimeString="2012-04-28T15:35:38-0400"
    />
</versions>