Listing object versions

Content Platform Tenant Management Help

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

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

Parameter Required Description
directory Yes Folder name.
file Yes Name of the file, including file extension.
version Yes Use the value list.
deleted No

By default, the GET request to retrieve object versions does not include delete records. To retrieve a listing that includes delete records, 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:

Element Attribute Description
versions path Path to the object.
versions utf8path UTF-8 compatible path to the object.
versions parentDir Parent directory of the object.
versions utf8parentDir UTF-8 compatible path to the parent directory of the object.
versions deleted Boolean value. Indicates whether the object is currently deleted.
versions showDeleted Boolean value. Indicates whether the list includes delete records.
versions namespaceName Name of the namespace where the object resides.
versions utf8NamespaceName UTF-8 compatible name of the namespace where the object resides.
entry urlname URL of the object
entry utf8Name UTF-8 compatible name of the object.
entry type Type of object. Default value is object.
entry size Size of the object in bytes.
entry hashScheme Type of hash algorithm, such as MD5.
entry hash Has value.
entry retention Retention in seconds after 1 January 1970
entry retentionString Retention day and time value
entry retentionClass Retention class name.
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.
entry version Version ID of the object.
entry ingestTime Seconds after 1 January 1970 that the object was either created or deleted.
entry ingestTimeString Ingested date and time.
entry changeTimeMilliseconds Seconds after 1 January 1970 that the object was either modified or deleted.
entry changeTimeString Change 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 records 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 or delete records 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"
/>

Status codes

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

Code Meaning Description
200 OK HCP successfully returned the version list.
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 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 records.

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>