Listing annotations for an object or version

You use the HTTP GET method to list the annotations for an object or version.

Access permission

To list annotations, you need read permission.

Request header

GET /rest/directory/file?type=custom-metadata-info HTTP/1.1
ParameterRequiredDescription
directoryYesFolder name.
fileYesName of the file, including file extension.
typeYesUse the value custom-metadata-info
versionNoTo check whether an annotation exists for a specific object version, in addition to specifying the request elements listed above, specify this URL query parameter.

Response header

The list 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

ElementChild elementDescription
annotationsannotationEach annotation is in their own separate annotation element.
annotationnameAnnotation name.
annotationchangeTimeMillisecondsSeconds after 1 January 1970 that the object was either modified or deleted.
annotationchangeTimeStringChange 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.
annotationsizeAnnotation size in bytes.
annotationcontentTypeThe contentType element value is text/xml if the namespace is configured to check whether custom metadata is well-formed XML. Otherwise the value is unknown.

Return codes

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

CodeMeaningDescription
200OKHCP successfully listed the annotations for the object.
204No ContentThe specified object or version does not have any annotations.
404Not Found

One of:

  • HCP could not find an 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 annotations for an object

Here’s a sample HTTP GET request that lists the annotations for an object named Q1_2012.ppt in the quarterly_rpts directory.

Request with curl command line

curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
"https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt
?type=custom-metadata-info

Request in Python using PycURL

import pycurl
filehandle = open("Q1_2012.ppt.custom-metadata.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/Q1_2012.ppt?type=custom-metadata-info")
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/Q1_2012.ppt?type=custom-metadata-info 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: 1352389820
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: text/xml
Content-Length: 822

Response body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<annotations>
     <annotation>
         <name>report_data</name>
         <hash>SHA-256 F8C7D88D139D14D115BA5300CD352338B8A1D344...</hash>
         <changeTimeMilliseconds>1352322387000.00</changeTimeMilliseconds>
         <changeTimeString>2012-11-07T16:06:27-0500</changeTimeString>
         <size>35643</size>
         <contentType>text/xml</contentType>
     </annotation>
     <annotation>
         <name>default</name>
         <hash>SHA-256 F8C7D88D139D14D115BA5300CD352338B8A1D344...</hash>
         <changeTimeMilliseconds>1352386457000.00</changeTimeMilliseconds>
         <changeTimeString>2012-11-08T09:54:17-0500</changeTimeString>
         <size>908</size>
         <contentType>tex/xml</contentType>
     </annotation>
</annotations>