You use the HTTP
GET method to retrieve an annotation for an object or version of an object. The annotation is returned in the format it had before it was stored.
You can also use a single request to retrieve object or version data and custom metadata together.
Access permission
To retrieve an annotation, you need read permission.
Request header
GET /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. |
| nowait | No |
HCP may detect that a GET request will take a significant amount of time to return an object. You can choose to have the request fail in this situation instead of waiting for HCP to return the object. When a GET request fails because the request would take a significant amount of time to return an object and the nowait parameter is specified, HCP returns an HTTP 503 (Service Unavailable) error code. If this happens, retry the request a few times, waiting about thirty seconds between retries. |
| 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-Encoding
- Always gzip.
- This header is returned only if the response data is compressed.
- Content-Length
- The size of the returned data, in bytes.
- Content-Type
- Always text/xml.
- 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-ContentLength
- The size of the annotation, in bytes.
- This header is returned only if the request specifies a compressed response.
- 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.
Response body
The body of the HTTP response contains the annotation.
Status codes
The table below describes the HTTP status codes that have specific meaning for this request.
| Code | Meaning | Description |
|---|---|---|
| 200 | OK | HCP successfully retrieved the annotation. |
| 204 | No Content | The specified object does not the specified annotation. |
| 404 | Not Found |
One of:
|
| 406 | Not Acceptable | The request has an Accept-Encoding header that does not include gzip or *. |
| 503 | Service Unavailable | The request contains the nowait query parameter, and HCP determined that the request would have taken a significant amount of time to return the annotation. |
Example: Retrieving an annotation for an object
Here’s a sample HTTP GET request that retrieves the account_info annotation 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&annotation=account_info" > Q1_2012.ppt.custom-metadata.xml
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 \
&annotation=account_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&annotation= account_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: 1336490468 X-HCP-SoftwareVersion: 7.0.0.16 ETag: "9c604138ffb0f308a8552a3752e5a1be" Content-Type: text/xml Content-Length: 287 X-HCP-Type: annotation X-HCP-Size: 119459 X-HCP-ChangeTimeMilliseconds: 1335347627362.00 X-HCP-ChangeTimeString: 2012-04-25T05:53:47-0400 X-HCP-Hash: SHA-256 42C605FBFFCD7CEAC36BE62F294374F94503D1DC1793736...
Response body
<?xml version="1.0" ?>
<quarterly_rpt>
<preparation>
<prepared_by>Lee Green</prepared_by>
<department>Accounting</department>
<title>Budget Director</title>
</preparation>
<presentation_date>04-18-2012</presentation_date>
<slide_count>23</slide_count>
</quarterly_rpt>