Checking the existence of an annotation

You use the HTTP HEAD method to check whether an object or specific version of an object has a specific annotation.

Access permission

To check for the existence of an annotation, you need browse permission.

Request header

HEAD /rest/directory/file?type=custom-metadata&annotation=annotation HTTP/1.1
ParameterRequiredDescription
directoryYesFolder name.
fileYesName of the file, including file extension.
typeYesUse the value custom-metadata.
annotation NoUse a value of the name of the annotation. You can omit this parameter for the default annotation.Used in conjunction with the type parameter.
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 headers

The list below describes the request-specific response headers for this operation.

  • Content-Type

    Always text/xml.

  • Content-Length

    The size of the annotation, in bytes.

  • ETag

    The ETag of the object or version enclosed in double quotation marks ("). This header is returned only if the object has an ETag.

  • X-HCP-ChangeTimeMilliseconds

    The change time for the object, 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.

  • 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-Hash

    The cryptographic hash algorithm HCP uses, along with the cryptographic hash value stored for the object, in this format:

    X-HCP-Hash: hash-algorithmhash-value

    You can use the returned hash value to verify that the stored data is the same as the data you sent. To perform the verification, compare this value with a hash value that you generate from the original data.

    The

    X-HCP-Hash
    header is not returned for multipart objects.

  • X-HCP-Size

    The size of the object data, in bytes.

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

  • X-HCP-Type

    The object entity type.

If HCP does not find the specified annotation, it returns an X-HCP-ErrorMessage header with the message No annotation exists with name annotation-name.

Return codes

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

CodeMeaningDescription
200OKThe specified object has the requested annotation.
204No ContentThe specified object does not have the requested annotation.
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: Checking the existence of an annotation

Here’s a sample HTTP HEAD request that checks the existence of the report_data annotation for an object named Q1_2012.ppt in the quarterly_rpts directory.

Request with curl command line

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

Request in Python using PycURL

import pycurl
import StringIO
cin = StringIO.StringIO()
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 \
  &annotation=report_data")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.HEADER, 1)
curl.setopt(pycurl.NOBODY, 1)
curl.setopt(pycurl.WRITEFUNCTION, cin.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
print cin.getvalue()
curl.close()

Request headers

HEAD /rest/quarterly_rpts/Q1_2012.ppt?type=custom-metadata
&annotation=report_data 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: 1352396298
X-HCP-SoftwareVersion: 7.0.0.16
X-RequestId: 47306C879E376245
ETag: "8d604138ffb0f308a8552a3752e5a1be"
Content-Type: text/xml
Content-Length: 35643
X-HCP-Type: annotation
X-HCP-Size: 35643
X-HCP-ChangeTimeMilliseconds: 1352322160000.00
X-HCP-ChangeTimeString: 2012-11-07T16:02:40-0500
X-HCP-Hash: SHA-256 F8C7D88D139D14D115BA5300CD352338B8A1D344046DB2...