Storing an annotation

Content Platform Tenant Management Help

File Size
4269 KB
Part Number

You use the HTTP PUT method to store or replace an annotation for an existing object. Some namespaces are configured to require custom metadata to be well-formed XML. In this case, HCP rejects an annotation that is not well-formed XML and returns an HTTP 400 (Bad Request) error code.

An annotation is stored as a single unit. You can add it or replace it in its entirely, but you cannot add to or change an existing annotation. If you store an annotation with the same name as an existing annotation, the new metadata replaces the existing metadata.

In addition to storing an annotation for an existing object, you can use a single request to store object data and an annotation together.

Access permission

To store an annotation, you need write permission.

Usage consideration

A PUT to store an annotation may fail in either of these cases:

  • The XML has a large number of different elements and attributes. In this case, the request returns an HTTP 400 (Bad Request) error code.

    To prevent failures, try restructuring the XML to have fewer different elements and attributes. For example, try concatenating multiple element values, such as the different parts of an address, to create a new value for a single element.

    If you cannot restructure the XML to prevent failures, ask your tenant administrator about reconfiguring the namespace to prevent HCP from checking custom metadata XML.

  • A large number of clients try to store custom metadata for multiple objects at the same time. In this case, the request returns an HTTP 409 (Conflict) error code.

    To prevent failures, limit the number of concurrent requests from clients to the namespace.

Request header

PUT /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.
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.
type Yes Use the value custom-metadata.

Response headers

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

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.
header is not returned for multipart objects.

Status codes

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

Code Meaning Description
201 Created HCP successfully stored the annotation.
400 Bad Request

One of:

  • The URL in the request is not well-formed.
  • The namespace is configured with custom metadata XML checking enabled, and the request included custom metadata that is not well-formed XML.
  • The request has a Content-Encoding header that specifies gzip, but the annotation is not in gzip-compressed format.
  • The request contains an unsupported query parameter or an invalid value for a query parameter.
  • The specified object has ten annotations, and the request is trying to add an annotation.
  • The request contains an If-Match, If-None-Match, If-Modified-Since, or If-Unmodified-since header.

If more information about the error is available, the HTTP response headers include the HCP-specific X‑HCP-ErrorMessage header.

403 Forbidden

One of:

  • The Authorization header or hcp-ns-auth cookie specifies invalid credentials.
  • The namespace requires client authentication, and the request does not have an Authorization header or hcp-ns-auth cookie.
  • The user doesn’t have write permission.
  • The object is under retention, and the namespace does not allow adding or replacing annotations for objects under retention.
  • The namespace does not exist.
  • The access method (HTTP or HTTPS) is disabled.

If more information about the error is available, the response headers include the HCP-specific X‑HCP-ErrorMessage header.

404 Not 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.
413 File Too Large The request is trying to store a non-default annotation that is larger than one MB or a default annotation that is larger than one GB. The maximum size of the default annotation is one GB, and the maximum size for all other annotations is one MB
415 Unsupported Media Type The request has a Content-Encoding header with a value other than gzip.

Example: Storing an annotation for an object

Here’s a sample HTTP PUT request that stores an annotation named report_data containing XML specified in the Q1_2012.custom-metadata.xml file for an existing object named Q1_2012.ppt.

Request with curl command line

curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -iT Q1_2012.custom-metadata.xml "

Request in Python using PycURL

import pycurl
import os
filehandle = open("Q1_2012.custom-metadata.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
curl.setopt(pycurl.URL, " \
  /rest/quarterly_rpts/Q1_2012.ppt?type=custom-metadata \
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
print curl.getinfo(pycurl.RESPONSE_CODE)

Request headers

PUT /rest/quarterly_rpts/Q1_2012.ppt?type=custom-metadata&annotation=report_data HTTP/1.1
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Content-Length: 317

Response headers

HTTP/1.1 201 Created
X-HCP-Hash: SHA-256 20BA1FDC958D8519D11A4CC2D6D65EC64DD12466E456...
Location: /rest/quarterly_rpts/Q1_2012.ppt
X-HCP-Time: 1334829227
Content-Length: 0