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.
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 markers. To retrieve a listing that includes delete marker, specify this URL query parameter: deleted=true You can also specify |
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 alwaysfalse
.
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 paretn 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 markers. |
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 markers shows delete markers for both the object and the directory.
For example, assume you do the following:
- Create a maintenance subdirectory of the departments directory.
- Delete the maintenance directory.
- 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.
Code | Meaning | Description |
200 | OK | HCP successfully returned the version list. |
404 | Not Found |
One of:
|
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>