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
| Parameter | Required | Description |
|---|---|---|
| directory | Yes | Folder name. |
| file | Yes | Name of the file, including file extension. |
| type | Yes | Use the value custom-metadata. |
| annotation | No | Use a value of the name of the annotation. You can omit this parameter for the default annotation.Used in conjunction with the type parameter. |
| version | No | To 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-Hashheader 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.
Status codes
The table below describes the HTTP status codes that have specific meaning for this request.
| Code | Meaning | Description |
|---|---|---|
| 200 | OK | The specified object has the requested annotation. |
| 204 | No Content | The specified object does not have the requested annotation. |
| 404 | Not Found |
One of:
|
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...