REST API

Last updated
Save as PDF

This section of the Help contains information about using the REST namespace access protocol.

Accessing a namespace with the REST API

For access to namespaces, HCP supports a RESTful implementation of HTTP called the REST API. To access a namespace through this protocol, you can write applications that use any standard HTTP client library, or you can use a command-line tool, such as cURL, that supports HTTP. You can also use a web browser to access the namespace. The namespace configuration determines whether you need to use HTTP with SSL (HTTPS).

Using the REST API, you can store, view, retrieve, and delete objects. You can specify certain metadata when you store new objects and change the metadata for existing objects. You can add, replace, and delete custom metadata and ACLs and retrieve information about namespaces.

The REST API is compliant with HTTP/1.1, as specified by RFC 2616.

For you to access a namespace using the REST API, the API must be enabled in the namespace configuration. If you cannot use the REST API to access the namespace, contact your tenant administrator.

This chapter explains how to use the REST API to access and perform operations in namespaces.

The REST API examples in this book use cURL and Python with PycURL, a Python and Java® interface that uses the libcurl library. cURL and PycURL are both freely available open-source software. You can download them from http://curl.haxx.se.

NoteIn version 7.12.1 of PycURL, the PUT method was deprecated and replaced with UPLOAD. The Python examples in this book show UPLOAD but work equally well with PUT.

URLs for namespace access using the REST API

URL formats

The following sections show the URL formats you can use to access a namespace. These formats all use a domain name to identify the HCP system. As an alternative, you can use an IP address to identify the HCP system.

If the HCP system does not support DNS, you can use the client hosts file to enable access to a namespace by hostname.

Note

The URL formats and examples that follow show https. If the namespace configuration does not require SSL security for HTTP, you can specify http instead of https in your URLs.
If you use HTTPS, check with your tenant administrator as to whether you need to disable SSL certificate verification. With cURL, you do this by including the -k or --insecure option in the request command line. In Python with PycURL, you do this by setting the SSL_VERIFYPEER option to false or 0 (zero).

Namespace URL

The URL that identifies a namespace has this format:

https://namespace-name.tenant-name.hcp-domain-name

For example:

https://finance.europe.hcp.example.com

In this example:

finance
the namespace name.
europe
the tenant name.
hcp-example.com
is the domain name of the HCP system.

The URL for a namespace is not case sensitive.

URLs for accessing objects, directories, and symbolic links

To access the root of the namespace directory tree, append rest, in all lowercase letters, to the namespace URL, as in this example:

https://finance.europe.hcp.example.com/rest

To access a specific object, directory, or symbolic link in a namespace, append the directory or object path to the namespace URL and the interface identifier rest. The format for this is:

https://namespace-name.tenant-name.hcp-domain-name/rest/directory-path[/object-name]

Here’s a sample URL that identifies a directory:

https://finance.europe.hcp.example.com/rest/Corporate/Employees

Here’s a sample URL that identifies an object:

https://finance.europe.hcp.example.com/rest/Corporate/Employees/23_John_Doe.xls

The names of objects, directories, and symbolic links are case sensitive. You cannot tell from a URL whether it identifies an object, directory, or symbolic link.

URLs for namespace information

You may have access to multiple namespaces owned by a given tenant. To retrieve information about these namespaces, use this format for the URL:

https://namespace-name.tenant-name.hcp-domain-name/proc

In the URL, proc must be all-lowercase.

A URL used to retrieve information about multiple namespaces owned by a tenant must start with the name of one of the namespaces.

Using an IP address in a URL

Because you need to provide a hostname that includes the tenant and namespace names in all REST API requests, using the hostname is the simplest way to access a namespace. In some applications, however, using IP addresses may be more efficient than using the hostname.

If you use an IP address in the URL, you provide the hostname in an HTTP Host header.

In curl commands, you use the -H option and specify a Host header with the namespace name, tenant name, and domain name of the HCP system, in this format:

-H"Host:namespace-name.tenant-name.hcp-domain-name"

This example shows a complete curl command that uses an IP address:

curl -iT Q1_2012.ppt -k
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d”
    -H "Host: finance.europe.hcp.example.com"
    "https://192.168.130.14/rest/quarterly_rpts/Q1_2012.ppt"

In Python with PycURL, you specify an HTTPHEADER option, in this format:

curl.setopt(pycurl.HTTPHEADER, ["Host: namespace-name.
  tenant-name.hcp-domain-name"])

In the preceding syntax, the left and right brackets ([]) and parentheses (()) are part of the command and do not indicate optional or required components.

This example shows a Python script that uses an IP address:

import pycurl
import os
filehandle = open("Q1_2012.ppt", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.URL,
  "https://192.168.125.125/rest/quarterly_rpts/Q1_2012.ppt")
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d", "Host: finance.europe.hcp.example.com"])
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("Q1_2012.ppt"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()

URL considerations

The following considerations apply to specifying URLs in REST API requests against a namespace.

URL length

For all HTTP methods except POST, the portion of a URL after rest, excluding any appended parameters, is limited to 4,095 bytes. If a REST API request includes a URL that violates that limit, HCP returns an HTTP 414 (Request URI Too Large) error code.

URL character case

All elements of a URL except http, https, and the hostname are case sensitive.

Object names with non-ASCII, nonprintable characters

When you store an object or directory with non-ASCII, nonprintable characters in its name, those characters are percent-encoded in the name displayed back to you.

Regardless of how the name is displayed, the object or directory is stored with its original name, and you can access it either by its original name or by the name with the percent-encoded characters.

Percent-encoding for special characters

Some characters have special meaning when used in a URL and may be interpreted incorrectly when used for other purposes. To avoid ambiguity, percent-encode the special characters listed in the table below.

Percent-encoded values are not case sensitive.

Character	Percent-encoded values
Space	%20
Tab	%09
New line	%0A
Carriage return	%0D
+	%2B
%	%25
#	%23
?	%3F
&	%26
\	&5C

Quotation marks with URLs in command lines

When using a command-line tool to access the namespace through the REST API, you work in a Unix, Mac OS^® X, or Windows shell. Some characters in the commands you enter may have special meaning to the shell. For example, the ampersand (&) used in URLs to join multiple query parameters also often indicates that a process should be put in the background.

To avoid the possibility of the Unix, Mac OS X, or Windows shell misinterpreting special characters in a URL, always enclose the entire URL in double quotation marks.

Authenticating namespace access

If a namespace requires authenticated client access, you need to pass a username and password in every REST API request. If a namespace does not require authenticated client access, you can optionally pass a username and password in a REST API request or you can omit them to access the namespace anonymously.

NoteIf the namespace you are trying to access is configured to support Active Directory (AD) single sign-on, anonymous access requests to that namespace or objects in that namespace will fail.

To access the namespace as an authenticated user, you need a user account that’s defined in HCP. If HCP is configured to support Active Directory® (AD), applications can also use an AD user account that HCP recognizes to access a namespace through the REST API.

HCP also accepts AD authentication provided through the SPNEGO protocol or through the AD authentication header. For more information about SPNEGO, see http://tools.ietf.org/html/rfc4559.

If you specify a username in a REST API request, that username must identify a user account that has the permissions needed to perform the requested operation.

Regardless of whether the namespace requires client authentication, if you provide credentials in a REST API request, they must be valid. If you provide invalid credentials, HCP responds with an HTTP 403 (Forbidden) error code.

To provide credentials in a REST API request, you specify an authentication token in an HTTP Authorization request header.

HCP also accepts credentials provided in an hcp-ns-auth cookie. However, this method of providing credentials is being deprecated and should not be used in new applications. If you use both an Authorization header and an hcp-ns-auth cookie, HCP uses the header for authentication and ignores the cookie.

HCP authentication through the REST API

To authenticate with HCP through the REST API, construct an authentication token from a system-level user account or a tenant-level user account, and then submit it using a request header with all requests. Successful authentication requires encoding your account information.

Authentication token

An authentication token consists of a username in Base64-encoded format and a password that’s hashed using the MD5 hash algorithm, separated by a colon, like this:

base64-encoded-user-name:md5-hashed-password

For example, here’s the token for the Base64-encoded user name lgreen and the MD5-hashed password p4ssw0rd:

bGdyZWVu:2a9d119df47ff993b662a8ef36f9ea20

The GNU Core Utilities include the base64 and md5sum commands necessary to encode your account information. These commands convert text to Base64-encoded and MD5-hashed values, respectively. For more information about the GNU Core Utilities, see http://www.gnu.org/software/coreutils/.

Other tools that generate Base64-encoded and MD5-hashed values are available for download on the web. For security reasons, do not use interactive public web-based tools to generate these values.

The GNU Core Utilities include the base64 and md5sum commands, which convert text to Base64-encoded and MD5-hashed values, respectively. With these commands, a line such as this creates the required token:

echo `echo -n username | base64`:`echo -n password | md5sum` | awk
  '{print $1}'

The character before echo, before and after the colon, and following md5sum is a backtick (or grave accent). The -n option in the echo command prevents the command from appending a new line to the output. This is required to ensure correct Base64 and MD5 values.

Authorization header

You use the HTTP Authorization request header to provide the authentication token for an HCP management API request. The value of this header is HCP followed by the authentication token, in this format:

Authorization: HCP authentication-token

For example, here’s the Authorization header for a user named lgreen and password p4ssw0rd:

Authorization: HCP bGdyZWVu:2a9d119df47ff993b662a8ef36f9ea20

Specifying the Authorization header with cURL

With cURL, you use the -H option to specify a header. So, for example, a request to list the tenants for the HCP system named hcp.example.com might look like this:

curl -k -i -H "Authorization: HCP bGdyZWVu:2a9d119df47ff993b662a8ef36f9ea20"
    -H "Accept: application/xml"
    "https://admin.hcp.example.com:9090/mapi/tenants"

Specifying the authentication header in Python with PycURL

In Python with PycURL, you use the HTTPHEADER option to specify a header, as in this example:

curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
    bGdyZWVu:2a9d119df47ff993b662a8ef36f9ea20"])

Active Directory user authentication through the REST API

To authenticate to HCP with Active Directory, construct an authentication token from a AD user account, and then submit it using a request header with all requests. The user name and password does not need to be encoded.

NoteIf AD single sign-on is enabled for the namespace and you want to access the namespace anonymously, you need to specify all_users in plain text as the user name and not specify a password.

Active Directory authentication token

An AD authentication token consists of an AD username and password separated by a colon, like this:

AD-username:AD-password

For example, here’s the token for the username lgreen and the password p4ssw0rd:

lgreen@example.com:p4sswOrd

Active Directory authorization header

You use the HTTP Authorization request header to provide the authentication token for an AD user accessing HCP through the management API. The value of this header is AD followed by the authentication token, in this format:

Authorization: AD authentication-token

For example, here’s the Authorization header for a user named lgreen and password p4ssw0rd:

Authorization: AD lgreen@example.com:p4sswOrd

Specifying the Authorization header with cURL

With cURL, you use the -H option to specify a header. So, for example, a request to list the tenants for the HCP system named hcp.example.com might look like this:

curl -i -k -H "Authorization: AD lgreen@example.com:p4sswOrd"
    "Accept: application/xml" "https://admin.hcp.example.com:9090/mapi/tenants"

TipAfter you log in using the authorization AD header, the response header replies with an hcap Set-Cookie value. You can use this cookie for subsequent authentication requests instead of using the authoriation AD header. For example:

curl -ik  -b HCAP-Login="acmepKMUfWLEu" 
"https://tenant.hcp.example.com:9090/mapi/tenants"

Specifying the authentication header in Python with PycURL

In Python with PycURL, you use the HTTPHEADER option to specify a header, as in this example:

curl.setopt(pycurl.HTTPHEADER, ["Authorization: AD
    lgreen@example.com:p4sswOrd"])

Transmitting data in compressed format

To save bandwidth, you can compress object data, an annotation, or an ACL in GZIP format before sending it to HCP. In the PUT request, you tell HCP that data is compressed so that HCP knows to decompress the data before storing it.

Similarly, in a GET request, you can tell HCP to return object data, an annotation, or an ACL in compressed format. In this case, you need to decompress the returned data yourself.

HCP supports only the GZIP algorithm for compressed data transmission.

You tell HCP that the request body is compressed by including a Content-Encoding header with the value gzip in the HTTP PUT request. In this case, HCP uses the GZIP algorithm to decompress the received data.

You tell HCP to send a compressed response by specifying an Accept-Encoding header in the HTTP GET request. If the header specifies gzip, a list of compression algorithms that includes gzip, or *, HCP uses the GZIP algorithm to compress the data before sending it.

NoteHCP normally compresses the object data, annotations, and ACLs that it stores, so you don’t need to explicitly compress objects for storage. However, if you do need to store GZIP-compressed objects, annotations, or ACLs, do not use a Content-Encoding header. To retrieve stored GZIP-compressed data, do not use an Accept-Encoding header.

Responding system

When an HCP system participates in replication, REST API requests (except those that request information about a namespace) may be redirected to another system in the replication topology if the target system is unavailable. For this redirection to work, both the target namespace and the HCP system must be configured to support it.

The X-HCP-ServicedBySystem response header returns the name of the system that responded to the request. This header is returned regardless of whether the system is replicated.

Working with objects and versions

With the REST API, you can perform operations on individual objects. If the namespace you are using is configured to allow versioning, you can also store multiple versions of an object. You can use this technique, for example, to preserve multiple states of a file that changes over time.

Storing an object or version of an object

You use the HTTP PUT method to store an object or new version of an existing object in a namespace. You can optionally use this method to store the object or version data and custom metadata in a single operation.

To store versions, the namespace must be configured to allow versioning. When versioning is enabled, storing an object with the same name as an existing object creates a new version of the object.

You can store new versions of any object, including multipart objects created by using the multipart upload feature of the S3-compatible API, as long as the object is not under retention or on hold. You cannot store new versions of an object that is under retention or on hold.

By default, a new object inherits several metadata values from namespace configuration settings. A new version of an object inherits the metadata values of the previous version of the object. In either case, you can override this default metadata when you store the object or version.

TipTo store very large objects, use the S3-compatible API. With the S3 compatible API, you can break up the data for an object into multiple parts and upload the parts to HCP individually. The process of creating an object by uploading the data in parts is called multipart upload. The result of a multipart upload is a single object that behaves in the same way as objects for which all the data was stored by means of a single PUT object request.

Access permission

To store an object in a namespace, you need write permission for the namespace.

To store a version of an object in a namespace, you need write permission for the object or namespace.

Request header

PUT /rest/directory/file?type=whole-object&annotaton=annotation_location HTTP/1.1

The PUT request to store an object or version has these elements:

If you are accessing the namespace as an authenticated user, an Authorization header
A URL specifying the location in which to store the object
A body containing the fixed-content data to be stored in the namespace

You can use a single request to store object data and a single annotation. To do this, the request body must contain the fixed-content data to be stored, followed by the annotation content, with no delimiter between them. Additionally, specify the request elements in the next table.

Parameter	Required	Description
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
type	No	Use the value `whole-object` to retrieve a single object or version data.
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.

Response headers

The list below describes request-specific HTTP response headers returned by a successful request.

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-CustomMetadata Hash
The cryptographic hash algorithm HCP uses and the cryptographic hash value of the stored annotation, in this format:
```
X-HCP-CustomMetadataHash: hash-algorithm hash-value
```
You can use the returned hash value to verify that the content of the stored annotation is the same as the annotation content you sent. To do this, compare this value with a hash value that you generate from the original annotation content.
This header is returned only if the request contains both data and custom metadata.
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-VersionId
The version ID of the object.

Response body

Not applicable.

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 object. If versioning is enabled and an object with the same name already exists, HCP created a new version of the object.
304	Not Modified	A request to store a new version of an existing object specified an If-Modified-Since header, and the change time of the current version is at or before the time specified in the header.
400	Bad Request	One of: The URL in the request is not well-formed. The request has a Content-Encoding header that specifies `gzip`, but the data is not in Gzip compressed format. The request has a type=whole-object query parameter, and either: The request does not have an X-HCP-Size header. The X-HCP-Size header value is greater than the content length. The namespace has custom metadata XML checking enabled, and the request included an annotation that is not well-formed XML. If the request that causes this error contains both object data and an annotation, HCP creates an empty object before it returns the error. To resolve this issue, you can either: Fix the annotation and retry the request. Store the object again without the annotation, thereby replacing the empty object. You can then fix the annotation at a later time and add it in a separate request. A request to store a version of an existing object included an If-Match or If-None-Match header and the object does not yet have an ETag. The request contains an unsupported query parameter or an invalid value for a query parameter. If more information about the error is available, the HTTP response headers include the HCP product-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 does not have write permission. For a request to store a version of an existing object, the object is under retention. The namespace does not exist. The access method (HTTP or HTTPS) is disabled. If more information about the error is available, the HTTP response headers include the HCP product-specific X‑HCP-ErrorMessage header.
409	Conflict	One of: HCP could not store the object in the namespace because the object already exists and versioning is not enabled. HCP could not store a new version of an existing object because another version is currently being added. HCP could not evaluate conditional headers because a version of the object is currently being added.
412	Precondition Failed	One of: A request to store a new version of an object specified an If-Match header, and the ETag of the existing object does not match the value in the header. A request to store a new version of an existing object specified an If-None-Match header, and the ETag of the existing object matches the value in the header. A request to store a new version of an existing object specified an If-Unmodified-Since header, and the change time of the existing object is after the time specified in the header.
413	File Too Large	One of: Not enough space is available to store the object. Try the request again after objects or versions are deleted from the namespace or the namespace capacity is increased. The request is trying to store an object that is larger than 2 TB. HCP cannot store objects larger than 2 TB. The request is trying to store custom metadata that is larger than 1 GB. HCP cannot store custom metadata larger than 1 GB.
415	Unsupported Media Type	The request has a Content-Encoding header with a value other than `gzip`.

Storing an object or object version

Here is a sample HTTP PUT request that stores a new object or new version of an object named Q2_2020.ppt in the quarterly_rpts directory.

Request with curl command line

curl -k -iT Q2_2020.ppt
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q2_2020.ppt"

Request in Python using PycURL

import pycurl
import os
filehandle = open("Q2_2020.ppt", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
    bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \
    rest/quarterly_rpts/Q2_2020.ppt")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("Q1_2020.ppt"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()

Request headers

PUT /rest/quarterly_rpts/Q2_2020.ppt HTTP/1.1
Host: /finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Content-Length: 678400

Response headers

HTTP/1.1 201 Created
X-HCP-ServicedBySystem: hcp.example.com
ETag: "9c604138ffb0f308a8552a3752e5a1be"
Location: /rest/quarterly_rpts/Q2_2020.ppt
X-HCP-VersionId: 79885459513089
X-HCP-VersionCreateTimeMilliseconds: 1494364634616
X-HCP-Hash: SHA-256 E830B86212A66A792A79D58BB185EE63A4FADA76BB8A1...
X-HCP-Time: 1334858878
Content-Length: 0

Sending object or version data with an annotation (Unix)

Here is a Unix command line that uses an HTTP PUT request to store the object data and an annotation for a file named Q2_2020.ppt. The request stores the object in the quarterly_rpts directory.

The cat command appends the contents of the Q2_2020-custom-metadata.xml file to the contents of the Q2_2020.ppt file. The result is piped to a curl command that sends the data to HCP and saves the content of Q2_2020-custom-metadata.xml in an annotation named report_data.

Unix command line

cat Q2_2020.ppt Q2_2020-custom-metadata.xml | curl -k -iT -
    -H "X-HCP-Size: `stat -c %s Q2_2020.ppt`"
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q2_2020.ppt
    ?type=whole-object&annotation=report_data"

Request headers

PUT /rest/quarterly_rpts/Q2_2020.ppt?type=whole-object&annotaton=report_data HTTP/1.1
Host: /finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
X-HCP-Size: 678685
Content-Length: 678900

Response headers

HTTP/1.1 201 Created
X-HCP-ServicedBySystem: hcp.example.com
ETag: "9c604138ffb0f308a8552a3752e5a1be"
Location: /rest/quarterly_rpts/Q2_2020.ppt
X-HCP-VersionId: 79885459513089
X-HCP-VersionCreateTimeMilliseconds: 1494364634616
X-HCP-Hash: SHA-256 E830B86212A66A792A79D58BB185EE63A4FADA76BB8A1...
X-HCP-CustomMetadataHash: SHA-256 86212A6692A79D5B185EE63A4DA76BBC...
X-HCP-Time: 1334862493
Content-Length: 0

Sending object or version data with an annotation (Java)

Here is the partial implementation of a Java class named WholeIO. The implementation shows the WriteToHCP method, which uses a single HTTP PUT request to store data and an annotation for an object (or version).

This example assumes that the applicable imports are included in the full class implementation.

public class WholeIO {
  .
  .
  .
void WriteToHCP() throws Exception {
    /*
     * Set up the PUT request to store both object data and an
     * annotation.
     * This method assumes that the HTTP client has already been
     * initialized.
     */
    HttpPut httpRequest = new HttpPut(sHCPURLFilePath +
      "?type=whole-object");

    // Construct the Whole I/O Sequenced Stream with the object data
    // and annotation.
    FileInputStream dataFileStream = new FileInputStream(sBaseFileName);


    FileInputStream customMetadataStream =
      new FileInputStream(sBaseFileName + ".cm");

    SequenceInputStream wholeIOStream = new SequenceInputStream(
        dataFileStream, customMetadataStream);

    // Point the HttpRequest to the input stream.
    httpRequest.setEntity(new InputStreamEntity(wholeIOStream, -1));

    // Put the size of the data object data into the X-HCP-Size header.
    httpRequest.setHeader("X-HCP-Size",
      String.valueOf(dataFileStream.available()));

    // Create the HTTP Authorization Header.
    httpRequest.setHeader(HCPUtils.HTTP_AUTH_HEADER, "HCP " +
       sEncodedUserName + ":" + sEncodedPassword);

    /*
     * Now execute the PUT request.
     */
    HttpResponse httpResponse = mHttpClient.execute(httpRequest);

    // If the status code is anything BUT 200 range indicating success,
    // throw an exception.
    if (2 != (int)(httpResponse.getStatusLine().getStatusCode() / 100))
    {
      // Clean up after ourselves and release the HTTP connection to the
      // connection manager.
      EntityUtils.consume(httpResponse.getEntity())

      wholeIOStream.close();
      dataFileStream.close();
      customMetadataStream.close();

      throw new HttpResponseException(
         httpResponse.getStatusLine().getStatusCode(),
         "Unexpected status returned from " + httpRequest.getMethod()
         + " (" + httpResponse.getStatusLine().getStatusCode() + ": "
         + httpResponse.getStatusLine().getReasonPhrase() + ")");
    }

    // Clean up after ourselves and release the HTTP connection to the
    // connection manager.
    EntityUtils.consume(httpResponse.getEntity());

    wholeIOStream.close();
    dataFileStream.close();
    customMetadataStream.close();

  }
  .
  .
  .
}

Sending object data in compressed format (Unix)

Here is a Unix command line that uses the gzip utility to compress the

Q2_2020.ppt file and then pipes the compressed output to a curl command. The curl command makes an HTTP PUT request that sends the data and tells HCP that the data is compressed.

Request with gzip and curl commands

gzip -c Q2_2020.ppt |
    curl -k -T -
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -H "Content-Encoding: gzip"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q2_2020.ppt"

Request headers

PUT /rest/quarterly_rpts/Q2_2020.ppt HTTP/1.1
Host: /finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Content-Length: 678400
Transfer-Encoding: chunked
Content-Encoding: gzip
Expect: 100-continue

Response headers

HTTP/1.1 201 Created
X-HCP-ServicedBySystem: hcp.example.com
ETag: "9c604138ffb0f308a8552a3752e5a1be"
Location: /rest/quarterly_rpts/Q2_2020.ppt
X-HCP-VersionId: 79885459513089
X-HCP-VersionCreateTimeMilliseconds: 1494364634616
X-HCP-Hash: SHA-256 E830B86212A66A792A79D58BB185EE63A4FADA76BB8A1...
X-HCP-Time: 1334862478
Content-Length: 0

Sending object data in compressed format (Java)

Here is the partial implementation of a Java class named HTTPCompression. The implementation shows the WriteToHCP method, which stores an object (or version) in an HCP namespace. The method compresses the data before sending it and uses the Content-Encoding header to tell HCP that the data is compressed.

The WriteToHCP method uses the GZIPCompressedInputStream helper class.

import org.apache.http.client.methods.HttpPut;
import org.apache.http.HttpResponse;
import org.apache.http.util.EntityUtils;
import com.hds.hcp.examples.GZIPCompressedInputStream;

class HTTPCompression {
   .
   .
   .
void WriteToHCP() throws Exception {

   /*
    * Set up the PUT request.
    *
    * This method assumes that the HTTP client has already been
     * initialized.
     */
    HttpPut httpRequest = new HttpPut(sHCPFilePath);

   // Indicate that the content encoding is gzip.
   httpRequest.setHeader("Content-Encoding", "gzip");

   // Open an input stream to the file that will be sent to HCP.
   // This file will be processed by the GZIPCompressedInputStream to
   // produce gzip-compressed content when read by the Apache HTTP client.
    GZIPCompressedInputStream compressedInputFile
      = new GZIPCompressedInputStream(new FileInputStream(
                                      sBaseFileName + ".toHCP"));

   // Point the HttpRequest to the input stream.
   httpRequest.setEntity(new InputStreamEntity(compressedInputFile, -1));

   // Create the HCP Authorization header.
   httpRequest.setHeader("Authorization", "HCP " + sEncodedUserName
                          + ":" + sEncodedPassword);

   /*
    * Now execute the PUT request.
    */
   HttpResponse httpResponse = mHttpClient.execute(httpRequest);

   /*
    * Process the HTTP response.
    */
   // If the status code is anything but in the 200 range indicating
   // success, throw an exception.
   if (2 != (int)(httpResponse.getStatusLine().getStatusCode() / 100))
   {
      // Clean up after ourselves and release the HTTP connection to the
      // connection manager.
      EntityUtils.consume(httpResponse.getEntity());

      throw new Exception("Unexpected HTTP status code: " +
      httpResponse.getStatusLine().getStatusCode() + " (" +
      httpResponse.getStatusLine().getReasonPhrase() + ")");
   }

   // Clean up after ourselves and release the HTTP connection to the
   // connection manager.
   EntityUtils.consume(httpResponse.getEntity());
}
   .
   .
   .
}

Copying an object or version of an object

You use the HTTP PUT method to copy an object or existing version of an object from one location to another. The copy operation has these characteristics:

The source location can be any namespace, including the default namespace.
The target location must be an HCP namespace within the source tenant and can include the source namespace.
The name of the target object can differ from the name of the source object.
The copied object inherits all its system metadata from the target namespace default values and does not have any ACL values. However, you can specify whether custom metadata is copied with the object data.
When versioning is enabled, the target object gets a new version ID that differs from the source object version ID.

You cannot store a new version of an object that is under retention or on hold in the target namespace.

Copying a large object can take some time. If a client times out because a copy operation is taking too long, HCP continues the operation in the background.

Because the connection to the client is broken, HCP cannot report the completion of the copy operation to the client. Until the operation is complete, HCP returns a 404 Not Found status code in response to HEAD requests for the object being created by the copy operation.

After a copy operation finishes successfully, HCP returns information about the new object in response to HEAD requests for the object. If the operation does not succeed, HCP continues to return a 404 Not Found status code in response to HEAD requests for the object.

If copy operations are causing a client to time out, consider increasing the client timeout interval.

NoteDepending on the replication configuration, copy operations may be slow, thereby increasing the likelihood of client timeouts.

Access permission

To copy an object or version, you need read permission for the source namespace and write permission for the target namespace.

Request header

PUT /rest/directory/file HTTP/1.1

The PUT request to copy an object or version of an object has these elements:

If you’re accessing the target namespace as an authenticated user, an Authorization header
An X-HCP-CopySource header in this format:
```
X-HCP-CopySource: source-namespace-name.source-tenant-name/source-object-path
```
The value of the X-HCP-CopySource header must be URL-encoded.
A URL specifying the location in which to store the object

NoteIf the X-HCP-CopySource header identifies a directory, HCP creates an empty directory with the path specified in the target URL, assuming the specified path does not already exist.

Parameter	Required	Description
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
version	No	One of: Specific version number of the file. For example: ?version=80232998058817 Range of version IDs, separated by a dash. For example: ?version=91728994618369-91728994618372 Range of create timestamps, separated by a dash. For example: ?version=@1493911519817-@1493911519817 `0-`, which provides all versions of an object. These rules apply to the `version` query parameter: If you omit the parameter, HCP checks the existence of the current version of an object. If you specify a valid range, HCP returns the requested amount of data with a status code of 200.
deleted	No	By default, the GET request to retrieve object versions does not include delete markers. To retrieve a listing that includes delete marker, specify this URL query parameter: deleted=true You can also specify `deleted=false`, which results in the default behavior.
forceEtag	No	To force HCP to generate an ETag for an object that does not yet have one, specify a `forceEtag` URL query parameter with a value of `true`.

Response headers

This option does not return any request-specific HCP-specific headers.

The request to copy an object returns an ETag header.

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

Response body

Not applicable.

Status codes

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

Code	Meaning	Description
201	Created	HCP successfully copied the object. If versioning is enabled and an object with the same name already exists, HCP created a new version of the object.
204	No Content	The requested version is a delete marker.
304	Not Modified	One of: A request to copy an object specified an `X-HCP-Copy-Source-If-None-Match` header, and the ETag of the source object matches the value in the header. A request to copy an object specified `X-HCP-Copy-Source-If-Modified-Since` header, and the source object change time is at or before the time specified in the header. A request to store a new version of an existing object specified an `If-Modified-Since` header, and the change time of the current version is at or before the time specified in the header.
400	Bad Request	The request was not valid. These are some, but not all, of the possible reasons: The URL in the request is not well-formed. Either the source or target namespace does not exist. The target namespace has custom metadata XML checking enabled, and the copied object includes custom metadata that is not well-formed XML. If the request that causes this error included an `X-HCP-MetadataDirective` header with the value `ALL`, HCP creates an empty object before it returns the error. To resolve this issue, you can either: Fix the custom metadata, and retry the request. Copy the object again without custom metadata, thereby replacing the empty object. You can then fix the custom metadata at a later time and add it in a separate request. The `X-HCP-CopySource` header identifies a symbolic link to an object. The request included an `If-Match` or `If-None-Match` header and an existing target object does not yet have an ETag. The request included an `X-HCP-CopySource-If-Match` or `X-HCP-CopySource-If-None-Match` header and did not include a `forceEtag` query parameter, and the source object does not yet have an ETag. The request contained an unsupported query parameter or an invalid value for a query parameter. 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 target location must be an HCP namespace within the source tenant. The target namespace requires client authentication, and the request does not include an `Authorization` header or `hcp-ns-auth` cookie. The user doesn’t have read permission in the source namespace or write permission in the target namespace. For a request to create a new version of an existing object, the object is under retention. The access method (HTTP or HTTPS) is disabled. If more information about the error is available, the HTTP response headers include the HCP-specific `X‑HCP-ErrorMessage` header.
404	Not Found	One of: The specified source object or object version does not exist. The current version of the specified source object is a delete marker, and the request did not specify a version ID. Any component of the source or target URL except for the last component in the path is a symbolic link to a directory.
409	Conflict	One of: HCP could not store the object in the namespace because the object already exists and versioning is not enabled. HCP could not store a new version of an existing object because another version is currently being added. HCP could not evaluate conditional headers because a version of the object is currently being added.
410	Gone	Possible reasons include: The source object exists, but the HCP system does not have the source object data. Retry the request, targeting a different system in the replication topology. The source object is in the process of being deleted.
412	Precondition Failed	One of: A request to copy an object specified an `X-HCP-Copy-Source-If-Match` header, and the ETag of the source object does not match the value in the header. A request to copy an object specified an `X-HCP-Copy-Source-If-Unmodified-Since` header, and the source object change time is after the time specified in the header. A request to copy a new version of an object specified an `If-Match` header, and the ETag of the target object does not match the value in the header. A request to copy a new version of an object specified an `If-None-Match` header, and the ETag of the target object matches the value in the header. A request to copy a new version of an object specified an `If-Unmodified-Since` header, and the target object change time is after the time specified in the header.
413	File Too Large	Not enough space is available to store the object. Try the request again after objects or versions are deleted from the target namespace or the namespace capacity is increased.
503	Service Unavailable	Possible reasons include: The specified version of the source object is a delete marker. HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator.

Example: Copying an object

Here’s a sample HTTP PUT request that copies an object named Q1_2012.ppt from the default namespace if the source object has been modified since midnight, Tuesday, January 1, 2013 EST. The request stores the object, using the source object name, in the finance namespace.

Request with curl command line

curl -k -i -X PUT
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -H "X-HCP-CopySource: default.europe/quarterly_rpts/Q1_2012.ppt"
    -H "X-HCP-CopySource-If-Modified-Since: Tue, Jan 1 2013 05:00:00 GMT"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt"

Request in Python using PycURL

import pycurl
import os
headers = ["Authorization: HCP
               bXl1c2Vy:3f3c6784e97531774380db177774ac8d",
           "X-HCP-CopySource: default.europe/quarterly_rpts/ \
               Q1_2012.ppt",
           "X-HCP-CopySource-If-Modified-Since:
               Tue, Jan 1 2013 05:00:00 GMT"
curl = pycurl.Curl()
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \
  rest/quarterly_rpts/Q1_2012.ppt")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.HTTPHEADER, headers)
curl.setopt(pycurl.PUT, 1)
curl.setopt(pycurl.INFILESIZE, 0
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

PUT /rest/quarterly_rpts/Q1_2012.ppt HTTP/1.1
Host: /finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
X-HCP-CopySource: default.europe/quarterly_rpts/Q1_2012.ppt
X-HCP-If-Modified-Since: Tue, Jan 01 2013 05:00:00 GMT"
Content-Length: 678400

Response headers

HTTP/1.1 200 Created
X-HCP-ServicedBySystem: hcp.example.com
Location: /rest/quarterly_rpts/Q1_2012.ppt
ETag: "9c604138ffb0f308a8552a3752e5a1be"
X-HCP-VersionId: 86675191823873
X-HCP-Hash: SHA-256 E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934C...
X-HCP-Time: 1354299872
Content-Length: 0

Checking the existence of an object or multiple versions of an object

You use the HTTP HEAD method to check whether an object, a version of an object, or a range of versions of an object exists in a namespace. These requests also retrieve the metadata for the object without retrieving the object data. The metadata is returned in HTTP response headers.

An HTTP 200 (OK) status code indicates that the requested object or object versions exist. An HTTP 404 (Not Found) status code indicates that the specified URL does not identify the object or its versions. Even if versioning is currently disabled, the method returns a 200 code and metadata if the requested version exists.

Using HEAD with a symbolic link verifies the existence of the object that is the target of the link.

Access permission

To verify the existence of an object or multiple object versions, you need browse permission.

Request header

HEAD /rest/directory/file?version=@version_num HTTP/1.1

The HEAD request to verify the existence of an object or multiple versions has these elements:

If you are accessing the namespace as an authenticated user, an Authorization header
The URL of the object or symbolic link

Parameter	Required	Description
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
version	No	One of: Specific version number of the file. For example: ?version=80232998058817 Range of version IDs, separated by a dash. For example: ?version=91728994618369-91728994618372 Range of create timestamps, separated by a dash. For example: ?version=@1493911519817-@1493911519817 `0-`, which provides all versions of an object. These rules apply to the `version` query parameter: If you omit the parameter, HCP checks the existence of the current version of an object. If you specify a valid range, HCP returns the requested amount of data with a status code of 200.
deleted	No	By default, the GET request to retrieve object versions does not include delete markers. To retrieve a listing that includes delete marker, specify this URL query parameter: deleted=true You can also specify `deleted=false`, which results in the default behavior.

Response headers

The following list describes request-specific response headers returned for this operation.

ChangeTimeString
The change time for the object in this format:
```
DDD, ddmmmyyyyhh:mm:ss GMT
```
For example, Fri, 18 Sep 2020 21:02:13 GMT.
This header contains the same datetime value as the X-HCP-ChangeTimeMilliseconds and X-HCP-ChangeTimeString headers, but in a format that can be used directly in If-Modified-Since and If-Unmodified-Since request headers.
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-ACL
A true or false value indicating whether the object has an ACL.
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-CurrentStorageNode
The IP address of a node on which object data is stored. You may get better performance retrieving an object if you use this IP address in the GET request for the object instead of using a host name in the request URL.
This header is returned only if both of these are true:
- HCP is configured to return the header.
- HCP has determined that a GET request for the object is likely to have better performance if the request is targeted to the IP address specified by the header.
X-HCP-Custom-Metadata
A true or false value indicating whether the object has any annotations.
X-HCP-CustomMetadataAnnotations
A comma-and-space-separated list containing the names and sizes of all object annotations. Each entry in the list consists of the annotation name, a semicolon (;) and the annotation size in bytes. For example: report_data; 12908.
This header is returned only if X-HCP-Custom-Metadata is true.
X-HCP-Domain
The Active Directory domain that contains the user identified by the X-HCP-Owner header.
This value is an empty string if the X-HCP-Owner header identifies a user account defined in HCP or if the object has no owner.
If the X-HCP-Owner header returns a user account ID or nobody, the value of the X-HCP-Domain header is one of several invalid domains that begin with the percent sign (%). These values have meanings internal to the HCP system.
X-HCP-DPL
The data protection level for the object.
X-HCP-GID
The POSIX group ID for the object.
For objects added through the NFS protocol, this value is determined by the NFS client.
This value is an empty string if either of these conditions is true:
- The object was added through a protocol other than NFS and neither the UID nor the GID for the object has been changed.
- The HCP product-specific owner of the object was changed.
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-Index
A true or false value indicating whether the object is marked for indexing.
X-HCP-IngestProtocol
The namespace access protocol through which the object was added to the namespace. Possible values are:
- CIFS_NFS
- HTTP
- SMTP
- WebDAV
If HCP cannot determine the protocol through which the object was added, this value is UNKNOWN.
X-HCP-IngestTime
The time when HCP stored the object, in seconds since January 1, 1970, at 00:00:00 UTC.
x-HCP-LabelRetentionHold
Specifies whether the object is on labeled hold. A Boolean value (true | false) is returned.
x-HCP-LabelRetentionHold-Labels
If the object is on labeled hold (X-HCP-LabelRetentionHold:true) and the user has privileged data access and read permissions on the object, this header is returned with a list of all labeled holds.
Example
```
X-HCP-LabelRetentionHold-Labels: [{"id":"UniqueLabelHold-1","hold": true},
[{"id":"UniqueLabelHold-2","hold": true },[{"id":"UniqueLabelHold-3","hold": true }]
```
X-HCP-LastVersionId
The version ID of the last returned object version.
X-HCP-Owner
The user that owns the object.
This value is an empty string if the object has no owner.
This value is nobody for objects that were stored by an authenticated user before the HCP system was upgraded from a release earlier than 5.0. These objects effectively have no owner.
This value is a user account ID if HCP can no longer identify the object owner by username. For example, you would see a user account ID if the HCP user account has been deleted.
X-HCP-Replicated
A true or false value indicating whether the object, has been replicated. The value is true only if the current version of the object, its system metadata, annotations (if any), and ACL (if any) have been replicated.
HCP returns this header only if either of these conditions is true:
- HCP is configured to return this header, and the request does not include the X-HCP-Get-Replicated header with a value of false.
- The request includes the X-HCP-Get-Replicated header with a value of true.
X-HCP-ReplicationCollision
A true or false value indicating whether the object is flagged as a replication collision.
X-HCP-Retention
The end of the retention period for the object. Possible values are:
- A time in seconds since January 1, 1970, at 00:00:00 UTC
- 0
- -1
- -2
X-HCP-RetentionClass
The name of the retention class to which the object belongs.
This value is an empty string if the object is not in a retention class.
X-HCP-RetentionHold
A true or false value indicating whether the object is on hold.
X-HCP-RetentionString
The end of the retention period for the object. Possible values are:
- A date and time in this format:
```
yyyy-MM-ddThh:mm:ssZ
```
  In this format, Z represents the offset from UTC and is specified as:
```
(+|-)hhmm
```
  For example, 2019-12-14T14:27:20-0500 represents the start of the 20th second into 2:27 PM, December 14, 2019, EST.
- Deletion Allowed
- Deletion Prohibited
- Initial Unspecified
X-HCP-Shred
A true or false value indicating whether HCP will shred the object after the object is deleted.
X-HCP-Size
The size of the object data, in bytes.
X-HCP-SoftwareVersion
The version number of the HCP software.
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.
X-HCP-UID
The POSIX user ID for the object.
For objects added through the NFS protocol, this value is determined by the NFS client.
This value is an empty string if either of these conditions are true:
- The object was added through a protocol other than NFS and neither the UID nor the GID for the object was changed.
- The HCP product-specific owner of the object was changed.
X-HCP-VersionId
The version ID of the object.

Response body

Not applicable.

Status codes

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

Code	Meaning	Description
200	OK	HCP found the specified object or version and returned its metadata. This code is also returned if the specified URL identifies a directory, not an object.
204	No Content	The requested version is a delete marker.
304	Not Modified	One of: The request specified an If-None-Match header, and the ETag of the requested object or version matches the value in the header. The request specified an If-Modified-Since header, and the object change time is at or before the time specified in the header.
400	Bad Request	The request was not valid. These are some, but not all, of the possible reasons: The URL in the request is not well-formed. The namespace does not exist. The request included an If-Match or If-None-Match header and the object does not yet have an ETag. The request contains an unsupported query parameter or an invalid value for a query parameter. If more information about the error is available, the HTTP response headers include the HCP product-specific X‑HCP-ErrorMessage header.
404	Not Found	One of: HCP did not find a directory, 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.
412	Precondition Failed	One of: The request specified an `If-Match` header, and the ETag of the requested object or version does not match the value in the header. The request specified an `If-Unmodified-Since` header, and the object change time is after the time specified in the header.

Checking the existence of an object

Here is a sample HTTP HEAD request that checks the existence of an object named Q2_2020.ppt in the quarterly_rpts directory.

Request with curl command line

curl -iI -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q2_2020.ppt"

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/Q2_2020.ppt")
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/Q2_2020.ppt HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-CurrentStorageNode: 172.20.27.21
X-HCP-Time: 1336490468
X-HCP-SoftwareVersion: 9.2.16
ETag: "8d604138ffb0f308a8552a3752e5a1be"
Content-Type: application/vnd.ms-powerpoint
Content-Length: 679116
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Type: object
X-HCP-Size: 679116
X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960...
X-HCP-VersionId: 80111794065921
X-HCP-IngestTime: 1334340948
X-HCP-RetentionClass: (SEC17a, A+7y)
X-HCP-RetentionString: 2022-12-19T09:51:47-0400
X-HCP-Retention: 1524131507
X-HCP-IngestProtocol: HTTP
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: true
X-HCP-Custom-Metadata: false
X-HCP-ACL: false
X-HCP-Owner: lgreen
X-HCP-Domain:
X-HCP-UID:
X-HCP-GID:
X-HCP-Replicated: false
X-HCP-ReplicationCollision: false
X-HCP-ChangeTimeMilliseconds: 1335347627362.00
X-HCP-ChangeTimeString: 2020-09-18T05:53:47-0400
Last-Modified: Wed, 18 Sep 2020 09:53:47 GMT

Checking the existence of an object version at a specified time

Here is a sample HTTP HEAD request that checks the existence of a version of an object named Q2_2020.ppt in the quarterly_rpts directory at the specified time of 80232998058817 using the object version ingest time.

Request with curl command line

curl -i -I -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q2_2020.ppt
    ?version=@1433265536867" > Q2_2020.ppt

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/Q2_2020.ppt?version=@1433265536867")
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/Q2_2020.ppt?version=@1433265536867 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
Date: Wed, 18 Sep 2020 16:42:45 GMT
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1433349765
X-HCP-SoftwareVersion: 9.2.16
ETag: "827ccb0eea8a706c4c34a16891f84e7b"
Expires: Fri, 18 Dec 2020 00:00:00 GMT
Content-Type: application/vnd.ms-powerpoint
Content-Disposition: attachment;
Content-Length: 678400
X-HCP-Type: object
X-HCP-Size: 678400
X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960...
X-HCP-VersionId: 80232998058817
X-HCP-IngestTime: 1433265536
X-HCP-RetentionClass:
X-HCP-RetentionString: Deletion Allowed
X-HCP-Retention: 0
X-HCP-IngestProtocol: HTTP
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: true
X-HCP-Custom-Metadata: false
X-HCP-ACL: false
X-HCP-Owner: myuser
X-HCP-Domain:
X-HCP-UID:
X-HCP-GID:
X-HCP-CustomMetadataAnnotations:
X-HCP-Replicated: false
X-HCP-ReplicationCollision: false
X-HCP-ChangeTimeMilliseconds: 1433265537266.00
X-HCP-ChangeTimeString: 2020-09-18T13:18:57-0400
Last-Modified: Fri, 18 Sep 2020 17:18:57 GMT

Checking the existence of a range of object versions

Here is a sample HTTP HEAD request that checks the existence of a range of object versions for an object named Q2_2020.ppt in the quarterly_rpts directory. The version range for the object is 80232998058817-80232998058819.

Request with curl command line

curl -i -I -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q2_2020.ppt
    ?version=80232998058817-80232998058819" > Q2_2020.ppt

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/Q2_2020.ppt?version=80232998058817-80232998058819")
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/Q2_2020.ppt?version=80232998058817-80232998058819 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
Date: Fri, 18 Sep 2020 18:21:14 GMT
X-HCP-ServicedBySystem: finance.europe.hcp.example.com
X-HCP-Time: 1434997274
X-HCP-SoftwareVersion: 9.2.16
X-HCP-LastVersionId: 80232998058819
Content-Length: 678400

Listing object versions

While versioning is enabled, you use the HTTP GET method to list the versions of an object. By default, the response body contains an XML listing that includes the current version and old versions that haven’t been pruned. It does not include versions that have been deleted. However, you can choose to include delete markers in the list.

If versioning is disabled, even if it was enabled in the past, HCP returns an HTTP 400 (Bad Request) error code in response to a request to list object versions. However, if versioning is then reenabled, HCP returns information about all old versions that have not been pruned.

Access permission

To list object versions, you need browse permission.

Request header

GET /rest/directory/file?version=list&deleted=true HTTP/1.1

The GET request to list object versions has these elements:

If you’re accessing the namespace as an authenticated user, an Authorization header.
The URL of the object.
A version=list URL query parameter.

If you specify a condition, the HCP returns a version list only if all versions of the object meet the specified condition.

Parameter	Required	Description
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
version	Yes	Use the value `list`.
deleted	No	By default, the GET request to retrieve object versions does not include delete markers. To retrieve a listing that includes delete marker, specify this URL query parameter: deleted=true You can also specify `deleted=false`, which results in the default behavior.

Response header

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

The body of the HTTP response to a GET request to list object versions contains an XML document listing the versions, in this format:

Element	Attribute	Description
versions	path	Path to the object.
versions	utf8path	UTF-8 compatible path to the object.
versions	parentDir	Parent directory of the object.
versions	utf8parentDir	UTF-8 compatible path to the paretn directory of the object.
versions	deleted	Boolean value. Indicates whether the object is currently deleted.
versions	showDeleted	Boolean value. Indicates whether the list includes delete markers.
versions	namespaceName	Name of the namespace where the object resides.
versions	utf8NamespaceName	UTF-8 compatible name of the namespace where the object resides.
entry	urlname	URL of the object
entry	utf8Name	UTF-8 compatible name of the object.
entry	type	Type of object. Default value is object.
entry	size	Size of the object in bytes.
entry	hashScheme	Type of hash algorithm, such as MD5.
entry	hash	Has value.
entry	retention	Retention in seconds after 1 January 1970
entry	retentionString	Retention day and time value
entry	retentionClass	Retention class name.
entry	hold	Boolean. Whether or not the object has a hold.
entry	shred	Boolean. Whether or not the object is to be shredded after it is deleted.
entry	index	Boolean. Whether or not the object is to be indexed.
entry	customMetadata	Boolean. Whether or not the object has custom metadata.
entry	customMetadataAnnotations	Annotations associated with the object. Delimited by semicolons.
entry	replicated	Boolean. Whether or not the object is replicated.
entry	owner	User name of the owner of the object. If there is no owner listed, the value is `nobody`.
entry	domain	Active Directory domain
entry	hasAcl	Boolean. Whether or not ACL is present for the object.
entry	state	Status is either `created` or `deleted`. Specifies whether the version contains data or is a marker indicating that the object was deleted.
entry	version	Version ID of the object.
entry	ingestTime	Seconds after 1 January 1970 that the object was either created or deleted.
entry	ingestTimeString	Ingested date and time.
entry	changeTimeMilliseconds	Seconds after 1 January 1970 that the object was either modified or deleted.
entry	changeTimeString	Change date and time.

If the directory that contains the object contained at some time a subdirectory with the same name as the object, the results of a version list request that includes delete markers shows delete markers for both the object and the directory.

For example, assume you do the following:

Create a maintenance subdirectory of the departments directory.
Delete the maintenance directory.
Save a maintenance object in the departments directory.

In this case, a version listing for the maintenance entry that includes delete markers shows these items:

An entry, with a version ID, for the deleted maintenance directory
Entries for all versions of the maintenance object, including any delete marker entries for the object

Version list entries for deleted directories look like this:

<entry urlname="object-name"
    utf8Name="utf8-object-name"
    type="directory"
    state="deleted"
    version=version-id"
    ingestTime="ingested-seconds-after-1/1/1970"
    ingestTimeString="ingested-datetime"
    changeTimeMilliseconds="change-millseconds-after-1/1/1970.unique-integer
    changeTimeString="yyyy-MM-ddThh:mm:ssZ"
/>

Status codes

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

Code	Meaning	Description
200	OK	HCP successfully returned the version list.
404	Not Found	One of: HCP could not find a directory, 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.

Code

Meaning

Description

200

HCP successfully returned the version list.

404

Not Found

One of:

HCP could not find a directory, 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 the versions of an object

Here’s a sample HTTP GET request that saves an XML listing of the versions of an object named Q1_2012.ppt located in the quarterly_rpts directory. The object has three versions: the original version that was ingested, a delete marker, and a version that was ingested after the original version was deleted. The request asks for all versions, including delete markers.

Request with curl command line

curl -i -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/
    Q1_2012.ppt?version=list&deleted=true" > Q1_2012-versions.xml

Request in Python using PycURL

import pycurl
filehandle = open("Q1_2012-versions.xml", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \
  quarterly_rpts/Q1_2012.ppt?version=list&deleted=true")
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)
filehandle.close()
curl.close()

Request headers

GET /rest/quarterly_rpts/Q1_2012.ppt?version=list&deleted=true 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: 1334915508
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: text/xml
Content-Length: 2080

Response body

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/static/xsl/ns-versions.xsl"?>
<versions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="/static/xsd/ns-versions.xsd"
        path="/rest/quarterly_rpts/Q1_2012.ppt"
        utf8path="/rest/quarterly_rpts/Q1_2012.ppt"
        parentDir="/rest/quarterly_rpts">
         utf8ParentDir="/rest/quarterly_rpts">
         deleted="false"
         showDeleted="true"
        namespaceName="finance"
         utf8NamespaceName="finance">
    <entry urlName="Q1_2012.ppt"
             utf8Name="Q1_2012.ppt"
             type="object"
             size="678400"
             hashScheme="SHA-256"
             hash="42C605FBFFCD7CEAC36BE62F294374F94503D1DC1793736EF..."
             retention="0"
             retentionString="Deletion Allowed"
             retentionClass=""
             hold="false"
             shred="false"
             dpl="2"
             index="true"
             customMetadata="false"
             customMetadataAnnotations=""
             replicated="false"
             owner="lgreen"
             domain=""
             hasAcl="false"
             state="created"
             version="80232488492929"
             ingestTime="1334829108"
             X-HCP-VersionCreateTimeMilliseconds="1494355864623"
             ingestTimeString="4/19/2012 9:51AM"
             changeTimeMilliseconds="1335347627362.00"
             changeTimeString="2012-04-25T09:53:47-0400"
    />
    <entry urlName="Q1_2012.ppt"
             utf8Name="Q1_2012.ppt"
             type="object"
             size="678400"
             hashScheme="SHA-256"
             hash="36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960B19..."
             retention="0"
             retentionString="Deletion Allowed"
             retentionClass=""
             hold="false"
             shred="false"
             dpl="2"
             index="true"
             customMetadata="false"
             customMetadataAnnotations=""
             replicated="false"
             owner="lgreen"
             domain=""
             hasAcl="false"
             state="deleted"
             version="80232488876481"
             ingestTime="1334829108"
             X-HCP-VersionCreateTimeMilliseconds="1494355864623"
             ingestTimeString="4/19/2012 9:51AM"
             changeTimeMilliseconds="1335607118753.00"
             changeTimeString="2011-04-28T09:58:38-0400"
    />
    <entry urlName="Q1_2012.ppt"
             utf8Name="Q1_2012.ppt"
             type="object"
             size="785690"
             hashScheme="SHA-256"
             hash="36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960B19..."
             retention="0"
             retentionString="Deletion Allowed"
             retentionClass=""
             hold="false"
             shred="false"
             dpl="2"
             index="true"
             customMetadata="false"
             customMetadataAnnotations=""
             replicated="false"
             owner="lgreen"
             domain=""
             hasAcl="false"
             state="created"
             version="80232489767169"
             ingestTime="1335613062"
             X-HCP-VersionCreateTimeMilliseconds="1494355864623"
             ingestTimeString="4/28/2012 11:37AM"
             changeTimeMilliseconds="1335627338110.00"
             changeTimeString="2012-04-28T15:35:38-0400"
    />
</versions>

Retrieving an object or multiple versions of an object

You use the HTTP GET method to retrieve an object, a version of an object, or a range of versions of an object from a namespace. When retrieving an single object or version, you can request all the object data or part of the data. When retrieving multiple versions of an object, you can only request all the object data.

You can use a GET request to retrieve all the object data of a single object or version and an annotation together. You cannot retrieve part of the object data together with an annotation in a single request. You can also use a GET request to retrieve the timestamp range of an object, which you can use to find a version of that object.

Using GET with a symbolic link returns the current version of the object that is the target of the link.

NoteAttempts to retrieve the current version of a deleted object result in an HTTP 404 (Not Found) error code. However, if versioning is enabled, you can retrieve the version you deleted by specifying its version ID.

Access permission

To retrieve an object or version, you need read permission.

Request header

GET /rest/directory/file?version=@version&deleted=true HTTP/1.1

The GET request to retrieve an object has these elements:

If you are accessing the namespace as an authenticated user, an Authorization header
The URL of the object or symbolic link

Parameter	Required	Description
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
version	No	One of: Specific version number of the file. For example: ?version=80232998058817 Range of version IDs, separated by a dash. For example: ?version=91728994618369-91728994618372 Range of create timestamps, separated by a dash. For example: ?version=@1493911519817-@1493911519817 `0-`, which provides all versions of an object. These rules apply to the `version` query parameter: If you omit the parameter, HCP checks the existence of the current version of an object. If you specify a valid range, HCP returns the requested amount of data with a status code of 200.
deleted	No	By default, the GET request to retrieve object versions does not include delete markers. To retrieve a listing that includes delete marker, specify this URL query parameter: deleted=true You can also specify `deleted=false`, which results in the default behavior.
forceEtag	No	To force HCP to generate an ETag for an object that does not yet have one, specify a `forceEtag` URL query parameter with a value of `true`.
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.
type	No	Use the value `whole-object` to retrieve a single object or version data.
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.

Response headers for retrieving a single object or version

The next list describes request-specific response headers for the retrieving a single object or version of the an object.

The response headers for retrieving multiple objects or object versions are described in the next section.

ChangeTimeString
The change time for the object in this format:
```
DDD, ddmmmyyyyhh:mm:ss GMT
```
For example, Fri, 18 Sep 2020 21:02:13 GMT.
This header contains the same datetime value as the X-HCP-ChangeTimeMilliseconds and X-HCP-ChangeTimeString headers, but in a format that can be used directly in If-Modified-Since and If-Unmodified-Since request headers.
Content-Encoding
Always gzip.
This header is returned only if HCP compressed the response before returning it.
Content-Length
The length, in bytes, of the returned data. These considerations apply:
- If you requested that the response be compressed, this is the compressed size of the returned data.
- If you requested uncompressed object data without custom metadata, the value of this header is the same as the value of the X-HCP-Size header.
- If you requested uncompressed partial content, the value is the size of the returned part. This value is equal to the difference between the start-position and end-position values in the Content-Range header plus one byte.
- If you requested uncompressed object data and custom metadata, the value is the sum of the size of the object data (the X-HCP-Size header) and the size of the custom metadata.
If the returned data is large, HCP might send a chunked response, which does not include this header.
Content-Range
Returned only when getting partial content.
The byte range of the returned object data, in this format:
```
start-position–end-position / object-size
```
where object-size is the total size of the object data and is the same as the value of the X-HCP-Size header.
Content-Type
The type of content for the object:
- If you requested all or part of the object data only, this is the Internet media type of the object data, such as text/plain or image/jpg.
- If you requested the object data and an annotation together, this value is always application/octet-stream.
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-ACL
A true or false value indicating whether the object has an ACL.
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 uncompressed length of the returned data. If the response returns object data only, this header and the X-HCP-Size header are equal.
This header is returned only if HCP compresses the data before returning it.
X-HCP-Custom-Metadata
A true or false value indicating whether the object has any annotations.
X-HCP-CustomMetadataAnnotations
A comma-and-space-separated list containing the names and sizes of all object annotations. Each entry in the list consists of the annotation name, a semicolon (;) and the annotation size in bytes. For example: report_data; 12908.
This header is returned only if X-HCP-Custom-Metadata is true.
X-HCP-CustomMetadataContentType
The annotation type, one of:
- text/xml
  If HCP checked for well-formed XML when the annotation was stored
- unknown
  otherwise
This header is returned only if the request asked for the object data and an annotation.
X-HCP-CustomMetadataFirst
One of:
- true
  The annotation precedes the object data.
- false
  The object data precedes the annotation.
X-HCP-DataContentType
The object Internet media type, such as text/plain or image/jpg.
This header is returned only if the request asked for the object data and an annotation.
X-HCP-Domain
The Active Directory domain that contains the user identified by the X-HCP-Owner header.
This value is an empty string if the X-HCP-Owner header identifies a user account defined in HCP or if the object has no owner.
If the X-HCP-Owner header returns a user account ID or nobody, the value of the X-HCP-Domain header is one of several invalid domains that begin with the percent sign (%). These values have meanings internal to the HCP system.
X-HCP-DPL
The data protection level for the object.
X-HCP-GID
The POSIX group ID for the object.
For objects added through the NFS protocol, this value is determined by the NFS client.
This value is an empty string if either of these conditions is true:
- The object was added through a protocol other than NFS and neither the UID nor the GID for the object has been changed.
- The HCP product-specific owner of the object was changed.
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-Index
A true or false value indicating whether the object is marked for indexing.
X-HCP-IngestProtocol
The namespace access protocol through which the object was added to the namespace. Possible values are:
- CIFS_NFS
- HTTP
- SMTP
- WebDAV
If HCP cannot determine the protocol through which the object was added, this value is UNKNOWN.
X-HCP-IngestTime
The time when HCP stored the object, in seconds since January 1, 1970, at 00:00:00 UTC.
x-HCP-LabelRetentionHold
Specifies whether the object is on labeled hold. A Boolean value (true | false) is returned.
x-HCP-LabelRetentionHold-Labels
If the object is on labeled hold (X-HCP-LabelRetentionHold:true) and the user has privileged data access and read permissions on the object, this header is returned with a list of all labeled holds.
Example
```
X-HCP-LabelRetentionHold-Labels: [{"id":"UniqueLabelHold-1","hold": true},
[{"id":"UniqueLabelHold-2","hold": true },[{"id":"UniqueLabelHold-3","hold": true }]
```
X-HCP-LastVersionId
The version ID of the last returned object version.
X-HCP-Owner
The user that owns the object.
This value is an empty string if the object has no owner.
This value is nobody for objects that were stored by an authenticated user before the HCP system was upgraded from a release earlier than 5.0. These objects effectively have no owner.
This value is a user account ID if HCP can no longer identify the object owner by username. For example, you would see a user account ID if the HCP user account has been deleted.
X-HCP-Replicated
A true or false value indicating whether the object, has been replicated. The value is true only if the current version of the object, its system metadata, annotations (if any), and ACL (if any) have been replicated.
HCP returns this header only if either of these conditions is true:
- HCP is configured to return this header, and the request does not include the X-HCP-Get-Replicated header with a value of false.
- The request includes the X-HCP-Get-Replicated header with a value of true.
X-HCP-ReplicationCollision
A true or false value indicating whether the object is flagged as a replication collision.
X-HCP-Retention
The end of the retention period for the object. Possible values are:
- A time in seconds since January 1, 1970, at 00:00:00 UTC
- 0
- -1
- -2
X-HCP-RetentionClass
The name of the retention class to which the object belongs.
This value is an empty string if the object is not in a retention class.
X-HCP-RetentionHold
A true or false value indicating whether the object is on hold.
X-HCP-RetentionString
The end of the retention period for the object. Possible values are:
- A date and time in this format:
```
yyyy-MM-ddThh:mm:ssZ
```
  In this format, Z represents the offset from UTC and is specified as:
```
(+|-)hhmm
```
  For example, 2019-12-14T14:27:20-0500 represents the start of the 20th second into 2:27 PM, December 14, 2019, EST.
- Deletion Allowed
- Deletion Prohibited
- Initial Unspecified
X-HCP-Shred
A true or false value indicating whether HCP will shred the object after the object is deleted.
X-HCP-Size
The size of the object data, in bytes.
X-HCP-SoftwareVersion
The version number of the HCP software.
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.
X-HCP-UID
The POSIX user ID for the object.
For objects added through the NFS protocol, this value is determined by the NFS client.
This value is an empty string if either of these conditions are true:
- The object was added through a protocol other than NFS and neither the UID nor the GID for the object was changed.
- The HCP product-specific owner of the object was changed.
X-HCP-VersionId
The version ID of the object.

Response headers for retrieving a range of object versions

The next list describes request-specific response headers for retrieving a range of object versions from a namespace.

When retrieving multiple versions of an object, you can only request all the object data. Four headers are returned for each object version, as described in the following list.

X-HCP-VersionID
The version ID of the object or object version.
X-HCP-Operation
Whether the object or object version is created or deleted.
X-HCP-IngestTimeMilliseconds
The time when HCP stored the object or object version, in seconds since January 1, 1970, at 00:00:00 UTC.
X-HCP-Size
The size of the object or object version in bytes.

Status codes

Code	Meaning	Description
200	OK	HCP successfully processed the request. This code is also returned if the URL specified a valid directory path and HCP returned a directory listing. Note: For a request for an object or version, if the number of bytes returned does not equal the value of the `Content-Length` response header, try the request again later.
204	No Content	The requested version is a delete marker.
206	Partial Content	HCP successfully retrieved the data in the byte range specified in the request.
304	Not Modified	One of: The request specified an `If-None-Match` header, and the ETag of the requested object or version matches the value in the header. The request specified an `If-Modified-Since` header, and the object change time is at or before the time specified in the header.
400	Bad Request	The request was not valid. Possible reasons include: The URL in the request is not well formed. The request has both a `type=whole-object` query parameter and a `Range` request header. The requested object is larger than 512,000 bytes and does not yet have an ETag, and the request included an `If-Match` or `If-None-Match` header that did not specify a `forceEtag=true` query parameter. The request contains an unsupported query parameter or an invalid value for a query parameter. If more information about the error is available, the response headers include the HCP product-specific `X‑HCP-ErrorMessage` header.
403	Forbidden	The requested operation is not allowed. Possible reasons include: 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 does not have read permission. 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 product-specific `X‑HCP-ErrorMessage` header.
404	Not Found	One of: HCP could not find an object, version, or directory 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. When retrieving object or version data and an annotation together, the requested object does not have an annotation with the specified name.
406	Not Acceptable	The request has an `Accept-Encoding` header that does not include `gzip` or `*`.
410	Gone	Possible reasons include: The object exists, but the HCP system does not have the object data. Retry the request, targeting a different system in the replication topology. The object is in the process of being deleted.
412	Precondition Failed	One of: The request specified an `If-Match` header, and the ETag of the requested object or version does not match the value in the header. The request specified an `If-Unmodified-Since` header, and the object change time is after the time specified in the header.
416	Requested Range Not Satisfiable	One of: The specified start position is greater than the size of the requested data. The size of the specified range is zero.
503	Service Unavailable	Possible reasons include: The request contains the `nowait` query parameter, and HCP determined that the request would have taken a significant amount of time to return the object. HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If the error persists, contact your tenant administrator.

Example: Retrieving all object data

Here’s a sample HTTP GET request that retrieves 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" >
Q1_2012.ppt

TipIf a GET request unexpectedly returns a zero-length file, use the -i parameter with curl to return the response headers in the target file. These headers may provide helpful information for diagnosing the problem.

Request in Python using PycURL

import pycurl
filehandle = open("Q1_2012.ppt", '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")
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 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-Time: 1336490468
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: application/vnd.ms-powerpoint
Content-Length: 678400
X-HCP-ServicedBySystem: hcp.example.com
ETag: "d45e5b124c1807d6ec4f8088b5e51f8d"
X-HCP-Type: object
X-HCP-Size: 678400
X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960...
X-HCP-VersionId: 80205544854849
X-HCP-IngestTime: 1334829227
X-HCP-RetentionClass:
X-HCP-RetentionString: Deletion Allowed
X-HCP-Retention: 0
X-HCP-IngestProtocol: HTTP
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: false
X-HCP-Custom-Metadata: false
X-HCP-ACL: false
X-HCP-Owner: lgreen
X-HCP-Domain:
X-HCP-UID:
X-HCP-GID:
X-HCP-Replicated: false
X-HCP-ReplicationCollision: false
X-HCP-ChangeTimeMilliseconds: 1335347627362.00
X-HCP-ChangeTimeString: 2012-04-25T05:53:47-0400
Last-Modified: Wed, 25 Apr 2012 09:53:47 GMT

Response body is the contents of the Q1_2012.ppt object

Example: Retrieving object data in compressed format (command line)

Here’s a sample curl command that tells HCP to compress the Q1_2012.ppt object before sending it to the client and then decompresses the returned content.

Request with curl command line

curl --compressed
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt" >
    Q1_2012.ppt -k

Request in Python using PycURL

import pycurl
filehandle = open("Q1_2012.ppt", '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")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.ENCODING, 'gzip')
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 HTTP/1.1
Host: finance.europe.hcp.example.com
Accept-Encoding: deflate, gzip
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-Time: 1336490468
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: application/vnd.ms-powerpoint
X-HCP-ServicedBySystem: hcp.example.com
ETag: "827ccb0eea8a706c4c34a16891f84e7b"
X-HCP-Type: object
X-HCP-Size: 678400
X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960...
X-HCP-VersionId: 80205544854849
X-HCP-IngestTime: 1334426531
X-HCP-RetentionClass:
X-HCP-RetentionString: Deletion Allowed
X-HCP-Retention: 0
X-HCP-IngestProtocol: HTTP
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: true
X-HCP-Custom-Metadata: false
X-HCP-ACL: false
X-HCP-Owner: myuser
X-HCP-Domain:
X-HCP-UID:
X-HCP-GID:
X-HCP-Replicated: false
X-HCP-ReplicationCollision: false
X-HCP-ChangeTimeMilliseconds: 1335347627362.00
X-HCP-ChangeTimeString: 2012-04-25T05:53:47-0400
Last-Modified: Wed, 25 Apr 2012 09:53:47 GMT
Content-Encoding: gzip
Transfer-Encoding: chunked

Response body: The contents of the Q1_2012.ppt object in gzip-compressed format.

Example: Retrieving object data in compressed format (Java)

Here’s the partial implementation of a Java class named HTTPCompression. The implementation shows the ReadFromHCP method, which retrieves an object from an HCP namespace. It uses the Accept-Encoding header to tell HCP to compress the object before returning it and then decompresses the results.

import org.apache.http.client.methods.HttpGet;
import org.apache.http.HttpResponse;
import org.apache.http.EntityUtils;
import java.util.zip.GZIPInputStream;

class HTTPCompression {
   .
   .
   .
void ReadFromHCP() throws Exception {

   /*
    * Set up the GET request.
    *
    * This method assumes that the HTTP client has already been
    * initialized.
    */
   HttpGet httpRequest = new HttpGet(sHCPFilePath);

   // Indicate that you want HCP to compress the returned data with gzip.
   httpRequest.setHeader("Accept-Encoding", "gzip");

   // Create the HCP authorization header.
   httpRequest.setHeader("Authorization", "HCP " + sEncodedUserName
                        + ":" + sEncodedPassword);

   /*
    * Now execute the GET request.
    */
   HttpResponse httpResponse = mHttpClient.execute(httpRequest);

   /*
    * Process the HTTP Response.
    */

   // If the status code is anything but in the 200 range indicating
   // success, throw an exception.
   if (2 != (int)(httpResponse.getStatusLine().getStatusCode() / 100))
   {
     // Clean up after ourselves and release the HTTP connection to the
     // connection manager.
     EntityUtils.consume(httpResponse.getEntity());

     throw new Exception("Unexpected HTTP status code: " +
       httpResponse.getStatusLine().getStatusCode() + " (" +
       httpResponse.getStatusLine().getReasonPhrase() + ")");
   }

   /*
    * Write the decompressed file to disk.
    */
   FileOutputStream outputFile = new FileOutputStream(
     sBaseFileName + ".fromHCP");

   // Build the string that contains the response body for return to the
   // caller.
   GZIPInputStream bodyISR = new
     GZIPInputStream(httpResponse.getEntity().getContent());
   byte partialRead[] = new byte[1024];
   int readSize = 0;
   while (-1 != (readSize = bodyISR.read(partialRead))) {
     outputFile.write(partialRead, 0, readSize);
   }

   // Clean up after ourselves and release the HTTP connection to the
   // connection manager.
   EntityUtils.consume(httpResponse.getEntity());
}
   .
   .
   .
}

Example: Retrieving a specific old version of an object

Here’s a sample HTTP GET request that retrieves version 80232998058817 of 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
    ?version=80232998058817" > Q1_2012.ppt

Request in Python using PycURL

import pycurl
filehandle = open("Q1_2012.ppt", '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%3Fversion=80232998058817")
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?version=80232998058817 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-Time: 1336490468
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: application/vnd.ms-powerpoint
Content-Length: 678400
X-HCP-ServicedBySystem: hcp.example.com
ETag: "827ccb0eea8a706c4c34a16891f84e7b"
X-HCP-Type: object
X-HCP-Size: 678400
X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960...
X-HCP-VersionId: 80232998058817
X-HCP-IngestTime: 1334426531
X-HCP-VersionCreateTimeMilliseconds: 1508940313887
X-HCP-RetentionClass:
X-HCP-RetentionString: Deletion Allowed
X-HCP-Retention: 0
X-HCP-IngestProtocol: HTTP
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: true
X-HCP-Custom-Metadata: false
X-HCP-ACL: false
X-HCP-Owner: myuser
X-HCP-Domain:
X-HCP-UID:
X-HCP-GID:
X-HCP-Replicated: false
X-HCP-ReplicationCollision: false
X-HCP-ChangeTimeMilliseconds: 1335347627362.00
X-HCP-ChangeTimeString: 2012-04-25T05:53:47-0400
Last-Modified: Wed, 25 Apr 2012 09:53:47 GMT

Response body: The contents of the requested version of the object.

Example: Retrieving the last object version created at a specified time

Here’s a sample HTTP GET request that retrieves the version of an object named Q1_2012.ppt in the quarterly_rpts directory that was created at 1433265536867.

Request with curl command line

curl -i -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt
    ?version=@1433265536867" > Q1_2012.ppt

Request in Python using PycURL

import pycurl
filehandle = open("Q1_2012.ppt", '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?version=@1433265536867")
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?version=@1433265536867 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
Date: Wed, 03 Jun 2015 16:42:45 GMT
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1433349765
X-HCP-SoftwareVersion: 7.2.0.346
ETag: "827ccb0eea8a706c4c34a16891f84e7b"
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/vnd.ms-powerpoint
Content-Disposition: attachment;
Content-Length: 678400
X-HCP-Type: object
X-HCP-Size: 678400
X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960...
X-HCP-VersionId: 80232998058817
X-HCP-IngestTime: 1433265536
X-HCP-VersionCreateTimeMilliseconds: 1508940313887
X-HCP-RetentionClass:
X-HCP-RetentionString: Deletion Allowed
X-HCP-Retention: 0
X-HCP-IngestProtocol: HTTP
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: true
X-HCP-Custom-Metadata: false
X-HCP-ACL: false
X-HCP-Owner: myuser
X-HCP-Domain:
X-HCP-UID:
X-HCP-GID:
X-HCP-CustomMetadataAnnotations:
X-HCP-Replicated: false
X-HCP-ReplicationCollision: false
X-HCP-ChangeTimeMilliseconds: 1433265537266.00
X-HCP-ChangeTimeString: 2015-06-02T13:18:57-0400
Last-Modified: Tue, 02 Jun 2015 17:18:57 GMT

Response body: The contents of the requested version of the object.

Example: Retrieving a range of an object's versions using version ID

Here’s a sample HTTP GET request that checks the existence of a range of object versions for an object named Q1_2012.ppt in the quarterly_rpts directory using version IDs. The version range for the object is 80232998058817-80232998058819.

Request with curl command line

curl -i -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt
    ?version=80232998058817-80232998058819" > Q1_2012.ppt

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?version=80232998058817-80232998058819")
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

GET /rest/quarterly_rpts/Q1_2012.ppt?version=80232998058817-80232998058819 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
Date: Wed, 03 Jun 2015 16:42:45 GMT
Expires: Thu, 01 Jan 1970 00:00:00 GMT
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1433349765
X-HCP-SoftwareVersion: 7.2.0.346
X-HCP-LastVersionId: 80232998058819
Content-Length: 678400

Response body

X-HCP-VersionId: 80232998058817
X-HCP-Operation: CREATE
X-HCP-IngestTimeMilliseconds: 1493911519817
X-HCP-Size: 9
The contents of the requested version of the object.

X-HCP-VersionId: 80232998058818
X-HCP-Operation: CREATE
X-HCP-IngestTimeMilliseconds: 1493911519818
X-HCP-Size: 9
The contents of the requested version of the object.

X-HCP-VersionId:80232998058819
X-HCP-Operation: CREATE
X-HCP-IngestTimeMilliseconds: 1493911519819
X-HCP-Size: 9
The contents of the requested version of the object.

Example: Retrieving a range of an object's versions using timestamp

Here’s a sample HTTP GET request that checks the existence of a range of object versions for an object named Q1_2012.ppt in the quarterly_rpts directory using ingest timestamps. The version ingest timestamp range for the object is @1493911519817–@1493911519820.

Request with curl command line

curl -i -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt
    ?version=@1493911519817–@1493911519820" > Q1_2012.ppt

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?version=@1493911519817–@1493911519820")
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

GET /rest/quarterly_rpts/Q1_2012.ppt?version=@1493911519817–@1493911519820 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
Date: Wed, 03 Jun 2015 16:42:45 GMT
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1433349765
X-HCP-SoftwareVersion: 7.2.0.346
X-HCP-LastVersionId: 80232998058819
Content-Length: 678400

Response body

X-HCP-VersionId: 80232998058817
X-HCP-Operation: CREATE
X-HCP-IngestTimeMilliseconds:
X-HCP-Size: 9
The contents of the requested version of the object.

X-HCP-VersionId: 80232998058818
X-HCP-Operation: CREATE
X-HCP-IngestTimeMilliseconds: 1493911519818
X-HCP-Size: 9
The contents of the requested version of the object.

X-HCP-VersionId: 80232998058819
X-HCP-Operation: CREATE
X-HCP-IngestTimeMilliseconds: 1493911519819
X-HCP-Size: 9
The contents of the requested version of the object.

Example: Retrieving object data and an annotation together (Java)

Here’s the partial implementation of a Java class named WholeIO. The implementation shows the ReadFromHCP method, which retrieves object data and an annotation named report_data in a single data stream, splits the object data from the annotation, and stores each in a separate file.

The ReadFromHCP method uses the WholeIOOutputStream helper class.

This example assumes that the applicable imports are included in the full class implementation.

class WholeIO {
   .
   .
   .
void ReadFromHCP() throws Exception {
     /*
      * Set up the GET request, specifying whole-object I/O.
      * This method assumes that the HTTP client has already been
      * initialized.
      */
     HttpGet httpRequest = new HttpGet(sHCPURLFilePath +
         "?type=whole-object&annotation=report_data");

     // Create the HTTP Authorization Header.
     httpRequest.setHeader(HCPUtils.HTTP_AUTH_HEADER, "HCP " + sEncodedUserName + ":" + sEncodedPassword);

     // Request the annotation before the object data.
     // This can be useful if the application examines the annotation
     // to set the context for the data that will follow.
     httpRequest.setHeader("X-HCP-CustomMetadataFirst", "true");

     /*
      * Now execute the GET request.
      */
     HttpResponse httpResponse = mHttpClient.execute(httpRequest);

     // If the status code is anything BUT 200 range indicating success
     // throw an exception.
     if (2 != (int)(httpResponse.getStatusLine().getStatusCode() / 100))
     {
       // Clean up after ourselves and release the HTTP connection to the
       // connection manager.
       EntityUtils.consume(httpResponse.getEntity());

       throw new HttpResponseException(
           httpResponse.getStatusLine().getStatusCode(),
           "Unexpected status returned from " + httpRequest.getMethod()
           + " (" + httpResponse.getStatusLine().getStatusCode() + ": "
           + httpResponse.getStatusLine().getReasonPhrase() + ")");
       }

     /*
      * Determine whether the object data or annotation is first.
      */
     Boolean cmFirst = new Boolean(httpResponse.getFirstHeader(
         "X-HCP-CustomMetadataFirst").getValue());

     /*
      * Determine the size of the first part based on whether the object
      * data or annotation is first.
      */

     // Assume the object data is first.
     int firstPartSize = Integer.valueOf(httpResponse.getFirstHeader(
         "X-HCP-Size").getValue());

     // If the annotation, do the math.
     if (cmFirst) {
       // subtract the data size from the content length returned.
       firstPartSize = Integer.valueOf(httpResponse.getFirstHeader(
           "Content-Length").getValue()) - firstPartSize;
     }

     /*
      * Split and write the file to disk.
      */
     WholeIOOutputStream outputCreator = new WholeIOOutputStream(
         new FileOutputStream(sBaseFileName + ".fromHCP"),
         new FileOutputStream(sBaseFileName + ".fromHCP.cm"),
         cmFirst);

     outputCreator.copy(httpResponse.getEntity().getContent(),
         firstPartSize);

     outputCreator.close(); // Files should be created.

     // Clean up after ourselves and release the HTTP connection to the
     // connection manager.
     EntityUtils.consume(httpResponse.getEntity());
  }

   .
   .
   .
}

Example: Retrieving partial object data

Here’s a sample HTTP GET request that retrieves the first 10,000 bytes of an object named status27.txt in the status directory.

Request with curl command line

curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -r 0-9999
    "https://finance.europe.hcp.example.com/rest/status/status27.txt" >
    status27a.txt

Request in Python using PycURL

import pycurl
filehandle = open("status27a.txt", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.RANGE, "0-9999")
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /rest/status/status27.txt")
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/status/status27.txt HTTP/1.1
Range: bytes=0-9999
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 206 Partial Content
X-HCP-Time: 1335347627
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: text/plain
Content-Range: bytes 0-9999/38985
Content-Length: 10000
X-HCP-ServicedBySystem: hcp.example.com
ETag: "39273c07f4709e6fea1c155c569fa29f"
X-HCP-Type: object
X-HCP-Size: 38985
X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960...
X-HCP-VersionId: 80232488876481
X-HCP-IngestTime: 1334851131
X-HCP-RetentionClass:
X-HCP-RetentionString: Deletion Allowed
X-HCP-Retention: 0
X-HCP-IngestProtocol: HTTP
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: true
X-HCP-Custom-Metadata: false
X-HCP-ACL: false
X-HCP-Owner: myuser
X-HCP-Domain:
X-HCP-UID:
X-HCP-GID:
X-HCP-Replicated: false
X-HCP-ReplicationCollision: false
X-HCP-ChangeTimeMilliseconds: 1335347627362.00
X-HCP-ChangeTimeString: 2012-04-25T05:53:47-0400
Last-Modified: Wed, 25 Apr 2012 09:53:47 GMT

Response body: The first 10,000 bytes of the contents of status27.txt

Deleting an object or object versions and using privileged delete

You use the HTTP DELETE method to delete an object. If versioning is enabled for a bucket, you can delete old versions of objects.

To delete a specific version of an object, you use a version ID or timestamp. To delete a range of versions of an object, you specify starting and ending version IDs or timestamps.

The result of an object or version deletion is a delete marker. A delete marker is an indicator that a version of an object has been deleted. A delete marker has a version ID but does not have any data or metadata.

Similar to purging an object, you can use a version ID or timestamp range to delete all versions of an object. However, purging an object does not result in delete markers.

If an object is under retention or on hold, you can delete it only if the namespace is configured to allow privileged operations and you have the necessary permissions. Privileged operations require you to provide a reason for the deletion.

TipIf an object is not under retention, you can use a privileged delete operation to specify a reason for the deletion. Although the object is not under retention, the namespace must still support privileged operations, and you need privileged permission.

Using the DELETE method with a symbolic link deletes the link, not the target object.

Access permission

To delete an object, you need delete permission.

To perform a privileged delete, even if the object is not under retention, you also need privileged permission.

Request header

DELETE /rest/directory/file HTTP/1.1

The DELETE request to delete an object has these elements:

If you’re accessing the namespace as an authenticated user, an Authorization header
The URL of the object or symbolic link

Parameter	Required	Description
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
version	No	One of: Specific version number of the file. For example: ?version=80232998058817 Range of version IDs, separated by a dash. For example: ?version=91728994618369-91728994618372 Range of create timestamps, separated by a dash. For example: ?version=@1493911519817-@1493911519817 `0-`, which provides all versions of an object. These rules apply to the `version` query parameter: If you omit the parameter, HCP checks the existence of the current version of an object. If you specify a valid range, HCP returns the requested amount of data with a status code of 200.
privileged	No	To perform a privileged delete, the request must specify both `privileged` and `reason` URL query parameters For example: ?privileged=true&reason=`reason-text`
reason	Yes, if `privileged` is used	Use percent-encode characters in the `reason` parameter that have special meanings in URLs.

Request body

To perform a privileged delete, the request body can include form-encoded data (application/x-www-form-urlencoded content type) in the request. For example, in cURL, you can use the -d option to specify form-encoded data in a DELETE request.

If you use form-encoded data, you need to percent-encode only ampersands (&) in the reason parameter. This prevents HCP from interpreting these characters as starting a new URL query parameter.

You cannot combine query parameters and form-encoded data in a single request.

Response header

This operation does not return any request-specific response headers.

Response body

Simply deleting an object has no request body.

Deleting a specific version of an object will get the contents of the requested version of the object.

Deleting a range of objects or multiple objects will include the following elements in the response body.

Element	Child element	Description
SuccessResult	VersionId	Version ID of the object that was successfully deleted.
ErrorResult	VersionId	Version ID of the object that could not be deleted.
ErrorResult	HttpResponseCode	HTTP status code that indicates why the object could not be deleted.

Status codes

Code	Meaning	Description
200	OK	HCP successfully deleted the object. This code is also returned if the URL specified a directory and HCP deleted the directory.
400	Bad Request	The request specified a conditional header, such as `If-Match`. 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 object is under retention. The user doesn’t have permission to perform the requested operation. 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 a directory, 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.
409	Conflict	HCP could not delete the specified object because the object is currently being written to the namespace.

Example: Deleting an object

Here’s a sample HTTP DELETE request that deletes the object named

Q1_2012.ppt from the quarterly_rpts directory in the namespace.

Request with curl command line

curl -k -iX DELETE
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt"

Request in Python using PycURL

import pycurl
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")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt 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: 1334425187
Content-Length: 0

Example: Deleting a specific old version of an object

Here’s a sample HTTP DELETE request that deletes version 80232998058817 of an object named Q1_2012.ppt in the quarterly_rpts directory.

Request with curl command line

curl -k -iX DELETE -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt
    ?version=80232998058817" > Q1_2012.ppt

Request in Python using PycURL

import pycurl
filehandle = open("Q1_2012.ppt", '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%3Fversion=80232998058817")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt?version=80232998058817 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-Time: 1336490468
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: application/vnd.ms-powerpoint
Content-Length: 678400
X-HCP-ServicedBySystem: hcp.example.com
ETag: "827ccb0eea8a706c4c34a16891f84e7b"
X-HCP-Type: object
X-HCP-Size: 678400
X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960...
X-HCP-VersionId: 80232998058817
X-HCP-IngestTime: 1334426531
X-HCP-RetentionClass:
X-HCP-RetentionString: Deletion Allowed
X-HCP-Retention: 0
X-HCP-IngestProtocol: HTTP
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: true
X-HCP-Custom-Metadata: false
X-HCP-ACL: false
X-HCP-Owner: myuser
X-HCP-Domain:
X-HCP-UID:
X-HCP-GID:
X-HCP-Replicated: false
X-HCP-ReplicationCollision: false
X-HCP-ChangeTimeMilliseconds: 1335347627362.00
X-HCP-ChangeTimeString: 2012-04-25T05:53:47-0400
Last-Modified: Wed, 25 Apr 2012 09:53:47 GMT

Response body: The contents of the requested version of the object.

Example: Deleting the last object version before at a specified time

Here’s a sample HTTP DELETE request that deletes the version of an object named Q1_2012.ppt in the quarterly_rpts directory that was ingested at 1433265536867, using the object version ingest time.

Request with curl command line

curl -k -iX DELETE -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt
    ?version=@80232998058817" > Q1_2012.ppt

Request in Python using PycURL

import pycurl
filehandle = open("Q1_2012.ppt", '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?version=@1433265536867")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt?version=@1433265536867 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
Date: Wed, 03 Jun 2015 16:42:45 GMT
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1433349765
X-HCP-SoftwareVersion: 7.2.0.346
ETag: "827ccb0eea8a706c4c34a16891f84e7b"
Expires: Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: application/vnd.ms-powerpoint
Content-Disposition: attachment;
Content-Length: 678400
X-HCP-Type: object
X-HCP-Size: 678400
X-HCP-Hash: SHA-256 36728BA190BC4C377FE4C1A57AEF9B6AFDA98720422960...
X-HCP-VersionId: 80232998058817
X-HCP-IngestTime: 1433265536
X-HCP-RetentionClass:
X-HCP-RetentionString: Deletion Allowed
X-HCP-Retention: 0
X-HCP-IngestProtocol: HTTP
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: true
X-HCP-Custom-Metadata: false
X-HCP-ACL: false
X-HCP-Owner: myuser
X-HCP-Domain:
X-HCP-UID:
X-HCP-GID:
X-HCP-CustomMetadataAnnotations:
X-HCP-Replicated: false
X-HCP-ReplicationCollision: false
X-HCP-ChangeTimeMilliseconds: 1433265537266.00
X-HCP-ChangeTimeString: 2015-06-02T13:18:57-0400
Last-Modified: Tue, 02 Jun 2015 17:18:57 GMT

Response body: The contents of the requested version of the object.

Example: Deleting a range of object versions using version ID

Here’s a sample HTTP DELETE request that deletes a range of object versions for an object named Q1_2012.ppt in the quarterly_rpts directory using version IDs. The version range for the object is 80232998058816-80232998058819. In this example, two objects are deleted successfully, and one delete fails.

Request with curl command line

curl -k -iX DELETE -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt
    ?version=80232998058816-80232998058819" > Q1_2012.ppt

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?version=80232998058817-80232998058819")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt?version=80232998058817-80232998058819 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
Date: Wed, 03 Jun 2015 16:42:45 GMT
Expires: Thu, 01 Jan 1970 00:00:00 GMT
X-HCP-ServicedBySystem: hcp.example.com

Response body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DeleteResult>
    <SuccessResult>
        <VersionId>80232998058817</VersionId>
    </SuccessResult>
    <SuccessResult>
        <VersionId>80232998058818</VersionId>
    </SuccessResult>
    <ErrorResult>
        <VersionId>80232998058819</VersionId>
        <HttpResponseCode>403</HttpResponseCode>
    </ErrorResult>
</DeleteResult>

Example: Deleting a range of object versions using timestamp

Here’s a sample HTTP DELETE request that deletes a range of object versions for an object named Q1_2012.ppt in the quarterly_rpts directory using ingest timestamps. The version ingest timestamp range for the object is @1493911519816–@1493911519820. In this example, two objects are deleted successfully, and one delete fails.

Request with curl command line

curl -k -iX DELETE -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt
    ?version=@1493911519816–@1493911519820" > Q1_2012.ppt

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?version=@1493911519817–@1493911519820")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt?version=@1493911519817–@1493911519820 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
Date: Wed, 03 Jun 2015 16:42:45 GMT
Expires: Thu, 01 Jan 1970 00:00:00 GMT
X-HCP-ServicedBySystem: hcp.example.com

Response body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DeleteResult>
    <SuccessResult>
        <VersionId>80232998058817</VersionId>
    </SuccessResult>
    <SuccessResult>
        <VersionId>80232998058818</VersionId>
    </SuccessResult>
    <ErrorResult>
        <VersionId>80232998058819</VersionId>
        <HttpResponseCode>403</HttpResponseCode>
    </ErrorResult>
</DeleteResult>

Example: Performing a privileged delete

Here’s a sample HTTP DELETE request that deletes the object named

Q1_2012.ppt, which is under retention, from the quarterly_rpts directory in the namespace.

Request with curl command line

curl -k -iX DELETE
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -d "privileged=true"
    -d "reason=Deleted per Compliance Order 12323."
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt"

Request in Python using PycURL

import pycurl
import urllib
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "http://finance.europe.hcp.example.com \
  /rest/quarterly_rpts/Q1_2012.ppt")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")

args = {'privileged':'true',
  'reason':'Deleted per Compliance Order 12323.'}
args = urllib.urlencode(args)
curl.setopt(pycurl.POSTFIELDS, args)

curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Content-Length: 65
Content-Type: application/x-www-form-urlencoded

Request body: Contains the privileged and reason parameters as form-encoded data.

Response headers

HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1334425187
Content-Length: 0

Purging an object and using privileged purge

You can use the HTTP DELETE method to purge all versions of an object from a namespace. You can also use the DELETE method to purge an object that is under retention (privileged purge) if the namespace is configured to allow privileged operations and you have the necessary permissions.

If versioning has never been enabled for the namespace, a purge request deletes the object. If versioning was enabled in the past but is no longer enabled, the purge request deletes all existing versions of the object.

TipIf an object is not under retention, you can use a privileged purge operation to specify a reason for the purge. Although the object is not under retention, the namespace must still support privileged operations, and you need the privileged permission.

Access permission

To purge objects you need both delete and purge permissions.

To perform a privileged purge operation, even if the object is not under retention, you also need privileged permission.

Request header

DELETE /rest/directory/file?purge=true HTTP/1.1

Parameter	Required	Description
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
purge	Yes	Use the value `true` to purge the object.
privileged	No	To perform a privileged delete, the request must specify both `privileged` and `reason` URL query parameters For example: ?privileged=true&reason=`reason-text`
reason	Yes, if `privileged` is used	Use percent-encode characters in the `reason` parameter that have special meanings in URLs.

Response header

This operation does not return any request-specific response headers.

Response body

Not applicable.

Status codes

Code	Meaning	Description
200	OK	HCP successfully purged all versions of the object.
400	Bad Request	The request specified a conditional header, such as If-Match. 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 object is under retention, and you do not have the privileged permission. The user doesn’t have permission to perform the requested operation. 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 a directory, 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.
409	Conflict	HCP could not purge the specified object because it is currently being written to the namespace.

Example: Purging an object

Here’s a sample HTTP DELETE request that purges all versions of the object named Q1_2012.ppt from the quarterly_rpts directory. This example uses a URL query string to pass the operation parameters.

Request with curl command line

curl -k -iX DELETE
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -k "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt
    ?purge=true"

Request in Python using PycURL

import pycurl
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?purge=true")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt?purge=true 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: 1334425187
Content-Length: 0

Example: Performing a privileged purge

Here’s a sample HTTP DELETE request that purges the object named

Q1_2012.ppt, which is under retention, from the quarterly_rpts directory. This example uses form-encoded data to pass the operation parameters and percent-encodes the reason because it contains an ampersand.

Request with curl command line

curl -k -iX DELETE
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -k -d "purge=true" -d "privileged=true"
    -d "reason=Purged%20per%20Compliance%20Dept.%20order%20AD%26943"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt"

Request in Python using PycURL

import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.example.hcp.com \
  /rest/quarterly_rpts/Q1_2012.ppt")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")

args = {'privileged':'true', 'purge':'true',
  'reason':'Purged per Compliance Dept. order AD&943'}
params = urllib.urlencode(args)
curl.setopt(pycurl.POSTFIELDS, params)

curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Content-Length: 90
Content-Type: application/x-www-form-urlencoded

Response headers

HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1334425187
Content-Length: 0

Conditional operations

Conditional operations let you tell HCP to perform an operation only if the current object or specified version meets certain conditions. A conditional operation can use an ETag or a datetime value. HCP compares the value that you provide in the header with the corresponding value for the object or version and performs the requested action only if the specified condition is met.

Here are two typical uses for conditional operations:

Managing a local object cache. You can reduce the load on HCP and your network by maintaining a local cache of frequently used objects. When the local application requires an object, it can send a conditional GET request to HCP to retrieve a new version only if the object has changed.
Managing storage by multiple users or applications. An application that updates an object can use a conditional PUT request that tells HCP to store the new version only if the ETag of the existing version equals the ETag of the last known version of the object. Otherwise, the application gets an error return, and can handle the data conflict appropriately. This technique can be useful in cases where several users might update the same object.

You can specify conditions in GET, HEAD, and PUT requests for objects and versions. You cannot use them in DELETE requests for these items. Doing so results in an HTTP 400 (Bad Request) error code.

NoteHCP ignores conditional headers in GET, HEAD, and PUT requests for annotations, ACLs, directories, and symbolic links and in POST requests for system metadata. It returns an HTTP 400 (Bad Request) error code in response to a conditional DELETE request for any of these items.

Request headers

You use the headers described in the table below to specify conditional operations.

Header	Value	Description
If-Match	One of: Comma-separated list of ETag values asterisk (*)	Perform the operation only if the ETag of the object or version is identical to one of the specified ETag values. For an asterisk, perform the operation if the object exists.
If-None-Match	One of: Comma-separated list of ETag values asterisk (*)	Perform the operation only if the ETag of the object or version is not equal to any of the specified ETag values. For an asterisk, perform the operation if the object doesn’t exist.
If-Modified-Since	Datetime value	Perform the operation only if the object or version change time was after the specified time.
If-Unmodified-Since	Datetime value	Perform the operation only if the object or version change time was at or before the specified time.

When you use the PUT method to copy an object, the headers listed in the table above apply to any existing version of the target object. You can use the headers describe in the table below to specify conditions for the source object.

Header	Contents	Description
X-HCP-CopySource-If-Match	One of: Comma-separated list of ETag values asterisk (*)	Perform the copy operation only if the ETag of the source object or version is equal to one of the specified ETag values. For an asterisk, perform the operation if the object exists.
X-HCP-CopySource-If-None-Match	One of: Comma-separated list of ETag values asterisk (*)	Perform the copy operation only if the ETag of the source object or version is not equal to any of the specified ETag values. For an asterisk, perform the operation if the object does not exist.
X-HCP-CopySource-If-Modified-Since	Datetime value	Perform the copy operation only if the source object or version change time was after the specified time.
X-HCP-CopySource-If-Unmodified-Since	Datetime value	Perform the copy operation only if the source object or version change time was at or before the specified time.

A request can specify more than one condition. In such a request:

HCP evaluates all the conditions. However, if the request includes both If-None-Match and If-Modified-Since headers, the If-Modified-Since header is ignored.
Headers that use ETag values are processed before headers that use datetime values.

ETag values

The list of ETag values used in the If-Match and If-None-Match header has this format:

"ETag-value"[, "ETag-value"]...

Because the individual ETag values are enclosed in double quotation marks ("), in curl and PycURL commands, you need to enclose the entire header in single quotation marks ('), as shown below:

'If-None-Match: "d158a5494cf76bf2cbbe40a7aa674543","638c9bd8d4c2c1022c6fcac9227f5af4"'

In the If-Match and If-None-Match headers, you typically use the ETag values returned in ETag headers of prior requests, such as when you store objects. This way, for example, you can prevent your application from retrieving a version of an object that your application has already cached or from storing an object version that already exists in HCP.

Datetime headers

Datetime headers let you perform operations based on whether an object has been modified since a specific time.

Datetime values for the If-Modified-Since and If-Unmodified-Since headers must be in one of these formats:

Format: DDD, dd MMM yyyy hh:mm:ss GMT
Example: Mon, 01 Jan 2013 15:30:00 GMT
The Last-Modified header returned by GET and HEAD requests for objects and versions is in this format.
Format: Day, dd-MMM-yy hh:mm:ss GMT
Example: Monday, 01-Jan-13 15:30:00 GMT
Format: DDD MMM d hh:mm:ss yyyy
Example: Mon Jan 1 15:30:00 2013

The following considerations apply to using datetime headers for conditional processing:

HCP compares the header value with the object change time. Several events, including system events, cause HCP to update the object change time.
Change time resolution is only to the second, so you cannot use these headers to differentiate between changes that happened during the same second.
If a header contains an invalid datetime value, HCP ignores the header and does not return an error response.

Handling objects that might not have ETags

If the HCP system has been upgraded from a release earlier than 6.0, some objects that were stored in the namespace before the upgrade may not yet have ETags. In such cases, the HCP behavior depends on the request type and object size, as follows:

For a GET request for an object 512,000 bytes or smaller, HCP automatically calculates the ETag, returns it in the ETag header and uses it, if needed, for conditional processing.
For a GET request for an object larger than 512,000 bytes, by default, HCP does not calculate the ETag. In this case:
- The response does not return an ETag header.
- If the request has an If-Match or If-None-Match header, HCP returns a 400 error response with a message explaining the cause.
For a PUT request to copy an object, HCP handles the source object the same way it handles the object in a GET request. For source objects of 512,000 bytes or less, HCP calculates and saves the ETag and uses it to processes any X-HCP-CopySource-If-Match or X-HCP-CopySource-If-None-Match header. For larger source objects, using these headers results in a 400 error response.
For a PUT or HEAD request, including for the target of a PUT request to copy an object, HCP does not generate the ETag for an existing object. If a PUT or HEAD request has an If-Match or If-None-Match header and specifies an object that does not yet have an ETag, HCP returns a 400 error.

If you get an error because an object does not have an ETag, you can force HCP to calculate the missing ETag by including a forceEtag query parameter with a value of true in either of these requests:

A GET request. In this case, HCP processes any If-Match or If-None-Match header and includes an ETag header when it returns an object.
A PUT request to copy an object. In this case, HCP processes any X-HCP-CopySource-If-Match or X-HCP-CopySource-If-None-Match header and can copy the specified object if the condition is met.

Once HCP has generated an object ETag, you can use conditional headers in GET, PUT, and HEAD requests for the object.

Example: Conditionally storing a new version

Here’s a sample HTTP PUT request that stores a new version of an object named Q3_2012.ppt in the quarterly_rpts directory if the current version of the object has not been modified since 9:00 a.m., EST on Monday, November 5, 2012.

Request with curl command line

curl -k -iT Q1_2012.ppt -H "If-Unmodified-Since: Mon, 05 Nov 2012 14:00:00
    GMT" -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt"

Request in Python using PycURL

import pycurl
import os
filehandle = open("Q3_2012.ppt", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com/ \
  rest/quarterly_rpts/Q3_2012.ppt")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.HTTPHEADER, ["If-Unmodified-Since: Mon, 05 Nov
  2012 14:00:00 GMT"])
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("Q1_2012.ppt"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()

Request headers

PUT /rest/quarterly_rpts/Q1_2012.ppt HTTP/1.1
Host: /finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
If-Unmodified-Since: Mon, 05 Nov 2012 14:00:00
Content-Length: 678400

Response headers

HTTP/1.1 201 Created
X-HCP-ServicedBySystem: hcp.example.com
ETag: 78821a05d282822e4abec190c061ba78
Location: /rest/quarterly_rpts/Q1_2012.ppt
X-HCP-VersionId: 79885459513089
X-HCP-Hash: SHA-256 E830B86212A66A792A79D58BB185EE63A4FADA76BB8A1...
X-HCP-Time: 1358245832
Content-Length: 0

Example: Conditionally retrieving all object data

Here’s a sample HTTP GET request that retrieves an object named

Q1_2012.ppt in the quarterly_rpts directory if the ETag of the object data does not match the ETag of version of the object that was previously retrieved from HCP. This technique prevents downloading a copy of an object that’s already available.

Request with curl command line

curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -H 'If-None-Match: "d158a5494cf76bf2cbbe40a7aa674543"'
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2012.ppt" >
    Q1_2012.ppt

Request in Python using PycURL

import pycurl
filehandle = open("Q1_2012.ppt", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d", "If-None-Match:
  d158a5494cf76bf2cbbe40a7aa674543"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /rest/quarterly_rpts/Q1_2012.ppt")
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 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
If-None-Match: d158a5494cf76bf2cbbe40a7aa674543

Response headers

HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1353352625
X-HCP-SoftwareVersion: 7.0.0.16
ETag: "d45e5b124c1807d6ec4f8088b5e51f8d"
Content-Type: application/vnd.ms-powerpoint
Content-Length: 130919
X-HCP-Type: object
X-HCP-Size: 130919
X-HCP-Hash: SHA-256 F19D0CA6D684F4B9C48789828A31551A50673597ABAC66C6D7....
X-HCP-VersionId: 86614553936513
X-HCP-IngestTime: 1353352405
X-HCP-RetentionClass:
X-HCP-RetentionString: Deletion Allowed
X-HCP-Retention: 0
X-HCP-IngestProtocol: HTTP
X-HCP-RetentionHold: false
X-HCP-Shred: false
X-HCP-DPL: 2
X-HCP-Index: true
X-HCP-Custom-Metadata: false
X-HCP-ACL: false
X-HCP-Owner: europe
X-HCP-Domain:
X-HCP-UID:
X-HCP-GID:
X-HCP-Replicated: false
X-HCP-ReplicationCollision: false
X-HCP-ChangeTimeMilliseconds: 1353352405323.00
X-HCP-ChangeTimeString: 2012-11-19T14:13:25-0500
Last-Modified: Mon, Nov 19 2012 19:13:25 GMT

Response body: The contents of the Q1_2012.ppt object

Working with directories

Creating an empty directory

You use the HTTP PUT method to create empty directories in a namespace. If any other directories in the path you specify for a new directory do not already exist, HCP creates them as well.

Access permission

To create a directory, you need write permission for the namespace.

Request header

PUT /rest/directory/new_dir?type=directory HTTP/1.1

The PUT request to create an empty directory has these elements:

If you’re accessing the namespace as an authenticated user, an Authorization header
A URL specifying the location in which to create the directory

Parameter	Required	Description
directory	Yes	Folder name.
new_dir	Yes	Name of the new directory you want to create.
type	Yes	Use the value `directory` to specify a directory object.

Response header

This creation operation does not return any request-specific response headers.

Status codes

Code	Meaning	Description
201	Created	HCP successfully created the directory.
409	Conflict	HCP could not create the directory in the namespace because a directory, object, or symbolic link with the specified name already exists.

Example: Creating an empty directory

Here’s a sample HTTP PUT request that creates a new directory named graphics in the quarterly_rpts directory.

Request with curl command line

curl -k -iX PUT
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/graphics
    ?type=directory"

Request in Python using PycURL

import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /rest/quarterly_rpts/graphics?type=directory")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "PUT")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

PUT /rest/quarterly_rpts/graphics?type=directory HTTP/1.1
Host: finance.europe.hcp.example.com
Authorizaton: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 201 Created
X-HCP-ServicedBySystem: hcp.example.com
Location: /rest/quarterly_rpts/graphics
Content-Length: 0

Checking the existence of a directory

You use the HTTP HEAD method to check whether a directory exists in a namespace.

Access permission

To check for directory existence, you need browse permission.

Request header

HEAD /rest/directory HTTP/1.1

The HEAD request to check the existence of a directory has these elements:

If you’re accessing the namespace as an authenticated user, an Authorization header

Parameter Required Description

directory Yes Folder name.

deleted

Parameter	Required	Description
directory	Yes	Folder name.
deleted	No	By default, the GET request to retrieve object versions does not include delete markers. To retrieve a listing that includes delete marker, specify this URL query parameter: deleted=true You can also specify `deleted=false`, which results in the default behavior.

By default, the GET request to retrieve object versions does not include delete markers. To retrieve a listing that includes delete marker, specify this URL query parameter:

deleted=true

You can also specify deleted=false, which results in the default behavior.

Response headers

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

X-HCP-Type
The object entity type.
X-HCP-ChangeTimeMilliseconds
The change time for the directory, 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.
The change time for a directory is the most recent of:
- The time the directory was created
- The time the directory was deleted
- The time an object was added to the directory
- The time an object was deleted from the directory
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-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.

Status codes

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

Code	Meaning	Description
200	OK	HCP found a directory or object at the specified URL.
404	Not Found	One of: HCP could not find a directory, object, or version at the specified URL. The specified directory does not exist, or the request specified a directory that has been deleted. Any component of the URL except for the last component in the path is a symbolic link to a directory.

Code

Meaning

Description

200

HCP found a directory or object at the specified URL.

404

Not Found

One of:

HCP could not find a directory, object, or version at the specified URL. The specified directory does not exist, or the request specified a directory 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 a directory

Here’s a sample HTTP HEAD request that checks the existence of a directory named quarterly_rpts.

Request with curl command line

curl -k -iI -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts"

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")
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 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: 1334829227
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: text/xm
X-HCP-ChangeTimeMilliseconds: 1326336965436
X-HCP-ChangeTimeString: 2012-01-11T09:56:05-0500
X-HCP-Type: directory
Content-Length: 0

Listing directory contents

You use the HTTP GET method to list the contents of a directory in a namespace. This method does not list old versions of objects.

Access permission

To list the contents of a directory, you need browse permission.

Request header

GET /rest/directory?deleted=true HTTP/1.1

Parameter	Required	Description
directory	Yes	Folder name.
delete	No	By default, a directory list does not include deleted objects or directories. If the namespace supports versioning, you can include deleted objects and directories in the list. To do this, specify this URL query parameter: deleted=true You can also specify `deleted=false`, which results in the default behavior. Also specify the `deleted=true` parameter to list the contents of a deleted directory (which can contain only deleted objects and directories).
mostRecentDirTimes	No	Either: `false`, the default, which shows the change time returned for each subdirectory in a directory list is the time the subdirectory was created or, if the subdirectory is a deleted directory, the time it was deleted. . `true`, which shows change times that are the most recent of The time the subdirectory was created The time the subdirectory was deleted The time an object was most recently added to the subdirectory The time an object was most recently deleted from the subdirectory

Response headers

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

X-HCP-Type
The object entity type.
X-HCP-ChangeTimeMilliseconds
The change time for the directory, 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.
The change time for a directory is the most recent of:
- The time the directory was created
- The time the directory was deleted
- The time an object was added to the directory
- The time an object was deleted from the directory
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-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

The body of the HTTP response consists of XML that lists the contents of the requested directory, including metadata for the objects the directory contains. It lists only the immediate directory contents, not the contents of any subdirectories.

Element	Attribute	Description
directory	path	Location of the directory.
directory	utf8path	UTF-8 compatible location of the directory.
directory	parentDir	Location of the parent directory.
directory	utf8ParentDir	UTF-8 compatible location of the parent directory.
directory	dirDeleted	Boolean value. Indicates whether the directory is currently deleted.
directory	showDeleted	Boolean value. Indicates whether the directory includes delete markers.
directory	namespaceName	Name of the namespace where the directory resides.
directory	utf8NamespaceName	UTF-8 compatible name of the namespace where the directory resides.
directory	changeTimeMilliseconds	Seconds after 1 January 1970 that the object was either modified or deleted.
directory	changeTimeString	Change 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.
entry	urlName	URL of the subdirectory, symbolic link, or object.
entry	utf8Name	UTF-8 compatible name of the subdirectory, symbolic link, or object.
entry	type	Subdirectories have the type `directory`. Symbolic links have the type `symlink`. All other objects have the type `object`.
entry	changeTimeMilliseconds	Seconds after 1 January 1970 that the object was either modified or deleted.
entry	changeTimeString	Change 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.
entry	state	Status is either `created` or `deleted`. Specifies whether the version contains data or is a marker indicating that the object was deleted.
entry	etag	Etags for the object.
entry	hashScheme	Type of hash algorithm, such as MD5. Not returned for multipart objects.
entry	hash	Hash value. Not returned for multipart objects.
entry	retention	Retention in seconds after 1 January 1970
entry	retentionString	Retention day and time value. In the time zone of the HCP system.
entry	retentionClass	Retention class name.
entry	ingestTime	Seconds after 1 January 1970 that the object was either created or deleted.
entry	ingestTimeString	Ingested date and time. In the time zone of the HCP system.
entry	hold	Boolean. Whether or not the object has a hold.
entry	shred	Boolean. Whether or not the object is to be shredded after it is deleted.
entry	index	Boolean. Whether or not the object is to be indexed.
entry	customMetadata	Boolean. Whether or not the object has custom metadata.
entry	customMetadataAnnotations	Annotations associated with the object. Delimited by semicolons.
entry	replicated	Boolean. Whether or not the object is replicated.
entry	owner	User name of the owner of the object. If there is no owner listed, the value is `nobody`.
entry	domain	Active Directory domain
entry	hasAcl	Boolean. Whether or not ACL is present for the object.
entry	state	Status is either `created` or `deleted`. Specifies whether the version contains data or is a marker indicating that the object was deleted.

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 directory listing. This code is also returned if the URL specified an object and HCP successfully retrieved the object.
404	Not Found	One of: HCP could not find a directory, 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.

Code

Meaning

Description

200

HCP successfully retrieved the directory listing. This code is also returned if the URL specified an object and HCP successfully retrieved the object.

404

Not Found

One of:

HCP could not find a directory, 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 the contents of a directory that includes deleted objects

Here’s a sample HTTP GET request that lists all the contents, including any deleted objects or subdirectories, of a directory named quarterly_rpts in a namespace that supports versioning.

Request with curl command line

curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts?deleted=true"
    > quarterly_rpts.xml

Request in Python using PycURL

import pycurl
filehandle = open("quarterly_rpts.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?deleted=true")
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?deleted=true 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: 1335036864
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: text/xml
X-HCP-Type: directory
X-HCP-ChangeTimeMilliseconds: 1353420657688.00
X-HCP-ChangeTimeString: 2012-11-20T09:10:57-0500
Content-Length: 577

Response body

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/static/xsl/ns-directory.xsl"?>
<directory xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="/static/xsd/ns-directory.xsd"
    path="/rest/quarterly_rpts"
    utf8Path="/rest/quarterly_rpts"
    parentDir="/rest">
    utf8ParentDir="/rest"
    dirDeleted="false"
    showDeleted="true"
    namespaceName="finance"
    utf8NamespaceName="finance">
    changeTimeMilliseconds="1326336965436"
    changeTimeString="2012-01-11T09:56:05-0500"

    <entry urlName="Q4_2011.ppt"
         utf8Name="Q4_2011.ppt"
         type="object"
         size="671744"
         hashScheme="SHA-256"
         hash="42C605FBFFCD7CEAC36BE62F294374F94503D1DC1793736EF367..."
         retention="0"
         retentionString="Deletion Allowed"
         retentionClass=""
         ingestTime="1326898187"
         ingestTimeString="1/18/2012 2:49PM"
         hold="false"
         shred="false"
         dpl="2"
         index="true"
         customMetadata="false"
         customMetadataAnnotations=""
         version="80238375537921"
         replicated="false"
         changeTimeMilliseconds="1326898187533.00"
         changeTimeString="2012-01-18T14:49:47-0400"
         owner="lgreen"
         domain=""
         hasAcl="false"
         state="created"
    />
    <entry urlName="obsolete"
         utf8Name="obsolete"
         type="directory"
         changeTimeMilliseconds="1331847677748.00"
         changeTimeString="2012-03-15T17:41:17-0400"
         state="deleted"
    />
    <entry urlName="Q1_2012.ppt"
         utf8Name="Q1_2012.ppt"
         type="object"
         size="678400"
         hashScheme="SHA-256"
         hash="E830B86212A66A792A79D58BB185EE63A4FADA76BB8A1C257C01..."
         retention="0"
         retentionString="Deletion Allowed"
         retentionClass=""
         ingestTime="1334847117"
         ingestTimeString="4/19/2012 9:51AM"
         hold="false"
         shred="false"
         dpl="2"
         index="true"
         customMetadata="false"
         customMetadataAnnotations=""
         version="80238376132993"
         replicated="false"
       changeTimeMilliseconds="1334847117598.00"
         changeTimeString="2012-04-19T09:51:57-0400"
         owner="lgreen"
         domain=""
         hasAcl="false"
         state="created"
    />
</directory>

Notice that the obsolete directory was deleted. It does not appear in a directory listing if the URL does not include the deleted=true parameter.

Deleting an empty directory

You use the HTTP DELETE method to delete an empty directory from a namespace. You cannot delete a directory that contains any objects, subdirectories, or symbolic links.

Access permission

To delete a directory you need delete permission for the namespace.

Request header

DELETE /rest/directory/empty_dir HTTP/1.1

Parameter	Required	Description
directory	Yes	Folder name.
empty_dir	Yes	Name of the empty directory that you want to delete.

Response header

This operation does not return any request-specific response headers.

Response body

Not applicable

Status codes

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

Code	Meaning	Description
200	OK	HCP successfully deleted the directory.
404	Not Found	The request specified a conditional header, such as `If-Match`. 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 specified directory is not empty. The user doesn’t have delete permission. 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 a directory, object, or version at the specified URL. The specified directory does not exist, or the request specified a directory that has been deleted. Any component of the URL except for the last component in the path is a symbolic link to a directory.
409	Conflict	HCP could not delete the specified directory because the directory is currently being written to the namespace.

Example: Deleting an empty directory

Here’s a sample HTTP DELETE request that deletes the directory named obsolete from the quarterly_rpts directory in the namespace.

Request with curl command line

curl -k -iX DELETE
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
   "https://finance.europe.hcp.example.com/rest/quarterly_rpts/obsolete”

Request in Python using PycURL

import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /rest/quarterly_rpts/obsolete")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/obsolete 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: 1334829227
Content-Length: 00

Working with system metadata

When converting legacy applications to use the RESTful HTTP interface to access an HCP namespace, be aware that the values used to specify certain metadata settings differ from those used for metadata settings in the default namespace and HCAP 2.x archives.

Specifying metadata on object creation

You use the HTTP PUT method to store an object in the namespace and override the default values for its metadata.

Access permission

To specify metadata in a request to store an object, you need write permission. Additionally, to specify the hold parameter, you also need privileged permission.

Request header

PUT /rest/directory/file?retention=retention HTTP/1.1

Parameter	Required	Description
acl	No	Stores a predefined ACL for the object. One of: all_read Grants read permission for the object to all users auth_read Grants read permission for the object to all authenticated users
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
hold	No	Places an object on hold or specifies that it is not on hold. Either `true` or `false`.
index	No	Specifies whether the object should be indexed for search. Either `true` or `false`.
label_hold	No	Specifies whether to place an object on labeled hold and if true, specifies a JSON format array containing pairs of one or more unique labeled hold IDs and an associated hold value. id Unique identifier string for the labeled hold. The maximum ID size is 64 characters. hold Specifies whether the object is on labeled hold using this `id`. Either `true` or `false`. Example label_hold=[{"id":"MY-HOLD-ID1","hold":true}, {"id":"MY-HOLD-ID2","hold":true}]
retention	No	Specifies the retention setting for the object. 0 (zero) or Deletion Allowed Allows the object to be deleted at any time. You can assign this value to an object only when you add it to the namespace or when its retention setting is -2. The value -0 is equivalent to 0 (zero). -1 or Deletion Prohibited Prevents the object from being deleted and its retention setting from being changed. You can assign this value to an object that is not in a retention class at any time. If an object is assigned to a retention class and that class is then deleted, the retention setting for that object changes to -1. -2 or Initial Unspecified Specifies that the object does not yet have a retention setting. You can assign this value to an object when you add the object to the namespace. You can also directly change the retention setting for an object from 0 to ‑2. You can change ‑2 to any other retention setting. `datetime` Prevents the object from being deleted until the specified date and time. You can assign this value to an object that is not in a retention class if the specified date and time is later than the current retention setting for the object. You cannot assign it to an object for which the current retention setting is -1. offset Specifies a period for which to retain the object. You can assign this value to an object that is not in a retention class at any time, except when its current retention setting is -1. HCP calculates the retention setting date and time from the offset and one of these: The time the object was added to the namespace The current retention setting The current time C+`retention_class_name` Assigns the object to a retention class. You can assign this value to an object if any one of these is true: The original retention period for the object has expired. The original retention period for the object has not expired, and the retention class results in a retention period that is longer than the current retention period. The retention setting for the object is 0 or -2. The retention setting for the object is -1, and the class has a retention setting of -1. The object is in a retention class, and the duration of the new class is not shorter than the duration of the original class. The retention class you assign must already be defined for the namespace.
shred	No	Specifies whether to shred the object after it is deleted. Either `true` or `false`.

Response headers

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

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-CustomMetadata Hash
The cryptographic hash algorithm HCP uses and the cryptographic hash value of the stored annotation, in this format:
```
X-HCP-CustomMetadataHash: hash-algorithm hash-value
```
You can use the returned hash value to verify that the content of the stored annotation is the same as the annotation content you sent. To do this, compare this value with a hash value that you generate from the original annotation content.
This header is returned only if the request contains both data and custom metadata.
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-VersionId
The version ID of the object.

Status codes

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

Code	Meaning	Description
400	OK	One of: The URL in the request is not well-formed. The request contains an unsupported query parameter or an invalid value for a query parameter. The request is trying to store an object with a predefined ACL in a namespace that does not support ACLs.

Code

Meaning

Description

400

One of:

The URL in the request is not well-formed.
The request contains an unsupported query parameter or an invalid value for a query parameter.
The request is trying to store an object with a predefined ACL in a namespace that does not support ACLs.

Example: Setting metadata when storing an object

Here’s a sample HTTP PUT request that stores a file named Q1_2012.ppt in the quarterly_rpts directory, sets the retention value for the object to the Reg-107 class, and sets the shred setting for the object to true.

Request with curl command line

curl -k -iT Q1_2012.ppt
    -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/
    Q1_2012.ppt?retention=C+Reg-107&shred=true"

Request in Python using PycURL

import pycurl
import os
filehandle = open("Q1_2012.ppt", 'rb')
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?retention=C+Reg-107")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("Q1_2012.ppt"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()

Request headers

PUT /rest/quarterly_rpts/Q1_2012.ppt?retention=C+Reg-107 HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Content-Length: 678400

Response headers

HTTP/1.1 201 Created
X-HCP-ServicedBySystem: hcp.example.com
ETag: "9c604138ffb0f308a8552a3752e5a1be"
Location: /rest/quarterly_rpts/Q1_2012.ppt
X-HCP-VersionId: 80238663473089
X-HCP-Hash: SHA-256 E830B86212A66A792A79D58BB185EE63A4FADA76BB8A1C...
X-HCP-Time: 1334829227
Content-Length: 0

Modifying object metadata

You use the HTTP POST method to change the metadata for existing objects in a namespace. The request changes only the metadata that it explicitly specifies. All other metadata remains unchanged.

You can modify metadata only for the current version of an object. You cannot modify metadata for an old version.

If the request to change metadata specifies a symbolic link, HCP changes the metadata on the object that’s the target of the link.

Access permission

To modify object metadata, you need write permission.

To specify a hold parameter, you also need privileged permission for the namespace.

To specify an owner parameter, you need change owner permission for the namespace.

Request header

POST /rest/directory/file HTTP/1.1

These considerations apply to requests to change object metadata:

You cannot change the hold and retention settings in the same request.
You cannot change the shred setting from true to false.

Parameter	Required	Description
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
domain		Specifies the Active Directory domain that contains the user account specified by the owner query parameter.
hold	No	Places an object on hold or specifies that it's not on hold. Either `true` or `false`.
index	No	Specifies whether the object should be indexed for search. Either `true` or `false`.
label_hold	No	Specifies whether to place an object on labeled hold and if true, specifies a JSON format array containing pairs of one or more unique labeled hold IDs and an associated hold value. id Unique identifier string for the labeled hold. The maximum ID size is 64 characters. hold Specifies whether the object is on labeled hold using this `id`. Either `true` or `false`. Example label_hold=[{"id":"MY-HOLD-ID1","hold":true}, {"id":"MY-HOLD-ID2","hold":true}]
owner	No	Specifies the user that owns the object. One of: The name of a user account that’s defined in HCP The name of an AD user account that HCP recognizes. This can be either the user principal name or the Security Accounts Manager (SAM) account name for the AD user account. If you specify an AD user account, you also need to specify the domain parameter. An empty string Specifying an empty string causes the object to have no owner.
retention	No	Specifies the retention setting for the object. 0 (zero) or Deletion Allowed Allows the object to be deleted at any time. You can assign this value to an object only when you add it to the namespace or when its retention setting is -2. The value -0 is equivalent to 0 (zero). -1 or Deletion Prohibited Prevents the object from being deleted and its retention setting from being changed. You can assign this value to an object that is not in a retention class at any time. If an object is assigned to a retention class and that class is then deleted, the retention setting for that object changes to -1. -2 or Initial Unspecified Specifies that the object does not yet have a retention setting. You can assign this value to an object when you add the object to the namespace. You can also directly change the retention setting for an object from 0 to ‑2. You can change ‑2 to any other retention setting. `datetime` Prevents the object from being deleted until the specified date and time. You can assign this value to an object that is not in a retention class if the specified date and time is later than the current retention setting for the object. You cannot assign it to an object for which the current retention setting is -1. offset Specifies a period for which to retain the object. You can assign this value to an object that is not in a retention class at any time, except when its current retention setting is -1. HCP calculates the retention setting date and time from the offset and one of these: The time the object was added to the namespace The current retention setting The current time C+`retention_class_name` Assigns the object to a retention class. You can assign this value to an object if any one of these is true: The original retention period for the object has expired. The original retention period for the object has not expired, and the retention class results in a retention period that is longer than the current retention period. The retention setting for the object is 0 or -2. The retention setting for the object is -1, and the class has a retention setting of -1. The object is in a retention class, and the duration of the new class is not shorter than the duration of the original class. The retention class you assign must already be defined for the namespace.
shred	No	Specifies whether to shred the object after it is deleted. Either `true` or `false`.

Response headers

This operation does not return any request-specific response headers.

Status codes

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

Code	Meaning	Description
200	OK	HCP successfully updated the metadata.
400	Bad Request	One of: The URL in the request is not well-formed. The request is trying to change the retention setting from a retention class to an explicit setting, such as a datetime value. The request is trying to change the retention setting and the retention hold setting at the same time. The request is trying to change the retention setting for an object on hold. The request is trying to change the shred setting from `true` to `false`. The request is trying to change the owner of an object and specifies an invalid username or domain. The request is trying to change the owner of an object to an AD user, but Active Directory authentication is not supported. The request contains an unsupported query parameter or an invalid value for a query parameter. If more information about the error is available, the response headers include the HCP product-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 does not have write permission. For a request to hold or release an object, the user does not have privileged permission. For a request to change the owner of an object, the user does not have change owner permission. The access method (HTTP or HTTPS) is disabled.
404	Not Found	HCP could not find the specified object, or the URL path contains a symbolic link to a directory anywhere other than in the last component.

Example: Changing multiple metadata values for an existing object

Here is a sample HTTP POST request that makes the following changes to the metadata for the Q1_2020.ppt file:

Increases retention by one year from the current value
Turns on shredding on delete
Turns off indexing

Request with curl command line

curl -k -i -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -d "retention=R+1y" -d "shred=true" -d "index=false"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/Q1_2020.ppt"

Request in Python using PycURL

import pycurl
curl = pycurl.Curl()
theHeader = ["Transfer-Encoding: chunked"]
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d", theHeader])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /rest/quarterly_rpts/Q1_2020.ppt")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.POST, 1)
theFields = "retention=R+1y&shred=true&index=false"
theHeader = ["Transfer-Encoding: chunked"]
curl.setopt(pycurl.POSTFIELDS, theFields)

curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

POST /rest/quarterly_rpts/Q1_2020.ppt HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Content-Length: 37
Content-Type: application/x-www-form-urlencoded

Response headers

HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
Content-Length: 0

Working with annotations

Storing an annotation

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.

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.

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 "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 os
filehandle = open("Q1_2012.custom-metadata.xml", 'rb')
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.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE,
  os.path.getsize("Q1_2012.custom-metadata.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()

Request headers

PUT /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
Content-Length: 317

Response headers

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

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

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

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

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

Parameter	Required	Description
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
type	Yes	Use the value `custom-metadata-info`
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 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

Element	Child element	Description
annotations	annotation	Each annotation is in their own separate `annotation` element.
annotation	name	Annotation name.
annotation	changeTimeMilliseconds	Seconds after 1 January 1970 that the object was either modified or deleted.
annotation	changeTimeString	Change 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.
annotation	size	Annotation size in bytes.
annotation	contentType	The 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`.

Status codes

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

Code	Meaning	Description
200	OK	HCP successfully listed the annotations for the object.
204	No Content	The specified object or version does not have any annotations.
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.

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>

Retrieving annotations for objects and versions

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

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: 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. The URL path contains a symbolic link to a directory anywhere other than in the last component.
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>

Deleting annotations

You use the HTTP DELETE request to delete an annotation for an object. You cannot delete annotations for old versions of an object.

Access permission

To delete an annotation, you need delete permission.

Request header

DELETE /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.

Response headers

This operation does not return any request-specific response headers.

Status codes

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

Code	Meaning	Description
200	OK	HCP successfully deleted the annotation.
204	No Content	The specified object does not have the specified annotation.
400	Bad Request	The request specified a conditional header, such as If-Match. 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 delete permission. The object is under retention, and the namespace does not allow deleting custom metadata for objects under retention. 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. The URL path contains a symbolic link to a directory anywhere other than in the last component.
409	Conflict	HCP could not delete the annotation because it is currently being written to the namespace.

Example: Deleting an annotation for an object

Here’s a sample HTTP DELETE request that deletes the report_data annotation for an object named Q1_2012.ppt located in the quarterly_rpts directory.

Request with curl command line

curl -k -iX DELETE
    -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
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.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /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-RequestId: E62EFD408DBB7B8F
X-HCP-Time: 1334829227
Content-Length: 0

Working with ACLs

Storing an ACL

You use the HTTP PUT method to store or replace an ACL for an existing object. ACLs can be specified in XML or JSON format. Unlike storing annotations, you can store an ACL for an object under retention.

An ACL 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 ACL. If you store an ACL for an object that already has an ACL, the new ACL replaces the existing ACL.

When you store an ACL for an object, the ACL is also stored for all old versions of that object.

You can use the HCP Search Console to modify ACLs on multiple objects with a single operation.

Access permission

To store or replace an ACL for an object, you need write ACL permission.

Usage consideration

The PUT of an ACL may fail with an HTTP 409 (Conflict) error code if a large number of clients try to store ACLs for multiple objects at the same time. In this case, limit the number of concurrent requests from clients to the namespace.

Request header

PUT /rest/directory/file?type=acl HTTP/1.1

Parameter	Required	Description
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
type	Yes	Use the value `acl`.

Response headers

This operation does not return any request-specific headers.

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 ACL.
400	Bad Request	One of: The request is trying to store an ACL in a namespace for which ACLs are not enabled. The ACL is not well-formed XML or JSON. The ACL includes an invalid entry or an invalid value for an entry. The ACL does not include a required entry. The ACL specifies a user, group, or domain that doesn’t exist. The ACL specifies an AD user or group but doesn’t include the `domain` entry. The ACL specifies an AD user or group, but the namespace does not support Active Directory authentication. Multiple `name` entries include the same user or group. A user or group can be specified in only one `name` entry in an ACL. The permissions you have specified in the ACL exceed your user permissions. The request is trying to store an ACL that contains more than one thousand access control entries. HCP cannot store ACLs that contain more than one thousand access control entries. The request has a `Content-Encoding` header that specifies `gzip`, but the ACL is not in gzip-compressed format. The URL in the request is not well-formed. The request contains an unsupported query parameter or an invalid value for a query parameter. 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. You don’t have write or write ACL permission. The namespace does not exist. The access method (HTTP or HTTPS) is disabled. If more information about the error is available, the HTTP response headers include the HCP-specific `X‑HCP-ErrorMessage` header.
404	Not Found	One of: HCP could not find the object for which you’re trying to store an ACL. The URL contains a symbolic link to a directory anywhere other than in the last component.
415	Unsupported Media Type	One of: The request has a `Content-Encoding` header with a value other than gzip. The request has a `Content-Type` header with a value other than `application/xml` or `application/json`. The request has a `Content-Type` header with a value that doesn’t correspond to the content type of the ACL body.

Example: Storing an ACL for an object

Here’s a sample HTTP PUT request that stores the ACL defined in the

Q1_2012.acl.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.acl.xml -H "Content-Type: application/xml"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/
    Q1_2012.ppt?type=acl"

Request in Python using PycURL

import pycurl
import os
filehandle = open("Q1_2012.acl.xml", 'rb')
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=acl")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("Q1_2012.acl.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()

Request headers

PUT /rest/quarterly_rpts/Q1_2012.ppt?type=acl HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Content-Length: 246

Response headers

HTTP/1.1 201 Created
X-HCP-ServicedBySystem: hcp.example.com
Location: /rest/quarterly_rpts/Q1_2012.ppt
X-HCP-Time: 1334772280
Content-Length: 0

Checking the existence of an ACL

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

Access permission

To check for the existence of an ACL, you need read ACL permission.

Request headers

HEAD /rest/directory/file?type=acl HTTP/1.1

Parameter	Required	Description
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
type	Yes	Use the value `acl`.
version	No	One of: Specific version number of the file. For example: ?version=80232998058817 Range of version IDs, separated by a dash. For example: ?version=91728994618369-91728994618372 Range of create timestamps, separated by a dash. For example: ?version=@1493911519817-@1493911519817 `0-`, which provides all versions of an object. These rules apply to the `version` query parameter: If you omit the parameter, HCP checks the existence of the current version of an object. If you specify a valid range, HCP returns the requested amount of data with a status code of 200.

Response headers

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

Content-Type
application/xml or application/json.
Content-Length
The size of the ACL in bytes. Zero if the object does not have an ACL.
X-HCP-ACL
A true or false value indicating whether the object has an ACL.
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.

Status codes

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

Code	Meaning	Description
200	OK	HCP found the specified object or version and returned its ACL existence information.
404	Not Found	One of: HCP could not find the specified object. The specified version is a delete marker. Any component of the URL except for the last component in the path is a symbolic link to a directory.

Code

Meaning

Description

200

HCP found the specified object or version and returned its ACL existence information.

404

Not Found

One of:

HCP could not find the specified object.
The specified version is a delete marker.
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 ACL

Here’s a sample HTTP HEAD request that checks the existence of an ACL 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=acl"

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=acl")
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=acl HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-Time: 1335016427
X-HCP-SoftwareVersion: 7.0.0.16
X-HCP-ACL: true
Content-Type: application/xml
Content-Length: 317

Retrieving ACLs for objects and versions

You use the HTTP GET method to retrieve an ACL for an object or version of an object. The ACL can be returned in either XML or JSON format.

Access permission

To retrieve an ACL for an object, you need read ACL permission.

Request header

GET /rest/directory/file?type=acl HTTP/1.1

Parameter	Required	Description
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
type	Yes	Use the value `acl`.
version	No	One of: Specific version number of the file. For example: ?version=80232998058817 Range of version IDs, separated by a dash. For example: ?version=91728994618369-91728994618372 Range of create timestamps, separated by a dash. For example: ?version=@1493911519817-@1493911519817 `0-`, which provides all versions of an object. These rules apply to the `version` query parameter: If you omit the parameter, HCP checks the existence of the current version of an object. If you specify a valid range, HCP returns the requested amount of data with a status code of 200.

Response headers

This operation returns Content-Length and Content-Type headers with information about the ACL. If the request specifies a gzip-compressed response, HCP returns a Content-Encoding header with a value of gzip.

This operation does not return any request-specific headers.

Response body

If an object has an ACL, the body of the HTTP response contains the ACL in XML or JSON.

If an object does not have an ACL, the body of the HTTP response contains:

In XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<accessControlList/>

In JSON:
```
{"grant":[]}
```

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 ACL. HCP returns this status code regardless of whether the object has an ACL. To determine whether an object has an ACL, view the response body for the request.
404	Not Found	One of: HCP could not find the specified object Any component of the URL except for the last component in the path is a symbolic link to a directory.
406	Not Acceptable	The request has an `Accept-Encoding` header that does not include `gzip` or `*`.

Example: Retrieving an ACL for an object

Here’s a sample HTTP GET request that retrieves the ACL 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=acl" > Q1_2012.ppt.acl.xml

Request in Python using PycURL

import pycurl
filehandle = open("Q1_2012.ppt.acl.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=acl")
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=acl HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-Time: 1335016427
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: application/xml
Content-Length: 263
X-HCP-ServicedBySystem: hcp.example.com

Response body

<accessControlList>
    <grant>
         <grantee>
             <name>all_users</name>
             <type>group</type>
         </grantee>
         <permissions>
             <permission>READ</permission>
         </permissions>
    </grant>
</accessControlList>

Deleting an ACL

You use the HTTP DELETE request to delete an ACL from an object. You cannot delete an ACL from an old version of an object.

Access permission

To delete an ACL, you need write ACL or delete permission.

Request header

DELETE /rest/directory/file?type=acl HTTP/1.1

Parameter	Required	Description
directory	Yes	Folder name.
file	Yes	Name of the file, including file extension.
type	Yes	Use the value `acl`.

Response headers

This operation does not return any request-specific response headers.

Status codes

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

Code	Meaning	Description
200	OK	HCP successfully deleted the ACL. HCP returns this status code even if the object does not have an ACL.
400	Bad Request	The request specified a conditional header, such as If-Match. If more information about the error is available, the HTTP response headers include the HCP-specific `X‑HCP-ErrorMessage` header.
404	Not Found	One of: HCP could not find the specified object Any component of the URL except for the last component in the path is a symbolic link to a directory.
409	Conflict	HCP could not delete the ACL because it is currently being written to the namespace.

Example: Deleting an ACL for an object

Here’s a sample HTTP DELETE request that deletes the ACL for an object named Q1_2012.ppt located in the quarterly_rpts directory.

Request with curl command line

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

Request in Python using PycURL

import pycurl
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=acl")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "DELETE")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

DELETE /rest/quarterly_rpts/Q1_2012.ppt?type=acl 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: 1334858680
Content-Length: 0

Retrieving namespace information

NoteA best practice is to limit your HTTP GET requests for retrieving statistics and metrics to once per hour. Polling the system more frequently can lead to system instability.

Listing accessible namespaces

You use the HTTP GET method to list the namespaces you can access. The list contains the namespaces owned by the specified tenant and for which you have any permissions.

Request headers

GET /proc HTTP/1.1

Response headers

This operation does not return any request-specific response headers.

Response body

If the user doesn’t have permissions for any of the tenant's namespaces, the namespaces element is empty.

Element	Attribute	Description
namespaces	tenantHostName	Domain and subdomain of the tenant host.
namespaces	httpScheme	Type of http connection to the tenant. Either `http` or `https`.
namespace	name	Name of the namespace
namespace	nameIDNA	URL of the namespace
namespace	versioningEnabled	Boolean. Specifies if versioning is enabled for the namespace.
namespace	searchEnabled	Boolean. Specifies if search is enabled for the namespace.
namespace	retentionMode	Specifies the retention mode for the namespace. Values are either `compliance` or `enterprise`.
namespace	defaultShredValue	Boolean. Specifies whether or not the objects in the namespace are shredded after deletion.
namespace	defaultIndexValue	Boolean. Specifies whether or not the objects in the namespace are indexed.
namespace	defaultRetentionValue	Specifies the retention value for the namespace.
namespace	hashScheme	Specifies the hash algorithm of the namespace.
namespace	dpl	Specifies the data protection level of the namespace.
namespace	description	Provides the description of the namespace.

Status codes

This operation does not have any request-specific status codes.

Example: Listing accessible namespaces

Here’s a sample HTTP GET request that returns information about the namespaces that are owned by the europe tenant in the hcp.example.com system and that can be accessed by the user identified by the Authorization header.

Request with curl command line

curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/proc"

Request in Python using PycURL

import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL,
  "https://finance.europe.hcp.example.com/proc")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

GET /proc HTTP/1.1
Host: /finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-Time: 1334326410
Content-Length: 1275

Response body

<namespaces xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="/static/xsd/proc-namespaces.xsd"
    tenantHostName="europe.hcp.example.com"
    httpScheme="https">
    <namespace name="finance"
         nameIDNA="finance"
         versioningEnabled="true"
         searchEnabled="true"
         retentionMode="enterprise"
         defaultShredValue="false"
         defaultIndexValue="true"
         defaultRetentionValue="0"
         hashScheme="SHA-256"
         dpl="2"
         >
        <description><![CDATA[
             Finance department
        ]]></description>
    </namespace>
    <namespace name="support"
         nameIDNA="support"
         versioningEnabled="true"
         searchEnabled="true"
        retentionMode="enterprise"
         defaultShredValue="false"
         defaultIndexValue="true"
         defaultRetentionValue="0"
         hashScheme="SHA-256"
         dpl="2"
         >
        <description><![CDATA[
             Technical Support department
        ]]></description>
    </namespace>
</namespaces>

Retrieving settings for an individual namespace

You use the HTTP GET method to retrieve the settings for an individual namespace. The response contains information about the namespace only if you have any permissions for the namespace.

Access permissions

If you’re accessing the namespace anonymously, the namespace you specify must allow anonymous access through the HTTP protocol.

Request header

GET /proc HTTP/1.1

Response header

This operation does not return any request-specific response headers.

Response body

Element	Attribute	Description
namespaces	tenantHostName	Domain and subdomain of the tenant host.
namespaces	httpScheme	Type of http connection to the tenant. Either `http` or `https`.
namespace	name	Name of the namespace
namespace	nameIDNA	URL of the namespace
namespace	versioningEnabled	Boolean. Specifies if versioning is enabled for the namespace.
namespace	searchEnabled	Boolean. Specifies if search is enabled for the namespace.
namespace	retentionMode	Specifies the retention mode for the namespace. Values are either `compliance` or `enterprise`.
namespace	defaultShredValue	Boolean. Specifies whether or not the objects in the namespace are shredded after deletion.
namespace	defaultIndexValue	Boolean. Specifies whether or not the objects in the namespace are indexed.
namespace	defaultRetentionValue	Specifies the retention value for the namespace.
namespace	hashScheme	Specifies the hash algorithm of the namespace.
namespace	dpl	Specifies the data protection level of the namespace.
namespace	description	Provides the description of the namespace.

Status codes

This operation does not have any request-specific status codes.

Example: Retrieving settings for an individual namespace

Here’s a sample HTTP GET request that returns the settings for the finance namespace owned by the europe tenant in the hcp.example.com system and that can be accessed by the user identified by the Authorization header.

Request with curl command line

curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/proc?single=true"

Request in Python using PycURL

import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL,
  "https://finance.europe.hcp.example.com/proc?single=true")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

GET /proc HTTP/1.1
Host: /finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-Time: 1334326410
Content-Length: 1275

Response body

<namespaces xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="/static/xsd/proc-namespaces.xsd"
    tenantHostName="europe.hcp.example.com"
    httpScheme="https">
    <namespace name="finance"
         nameIDNA="finance"
         versioningEnabled="true"
         searchEnabled="true"
         retentionMode="enterprise"
         defaultShredValue="false"
         defaultIndexValue="true"
         defaultRetentionValue="0"
         hashScheme="SHA-256"
         dpl="2"
         >
        <description><![CDATA[
            Finance department
        ]]></description>
    </namespace>
</namespaces>

Listing retention classes

You use the HTTP GET method to list the retention classes defined for a namespace.

Request header

GET /proc/retentionClasses HTTP/1.1

Response headers

This operation does not return any request-specific response headers.

Response body

Element	Attribute	Description
retentionClasses	namespaceName	Name of the namespace
retentionClass	name	Name of the retention class..
retentionClass	value	Value of the retention class.
retentionClass	autoDelete	Boolean. Whether or not objects in the namespace are automatically deleted.
retentionClass	description	Provides the description of the retention class.

Status codes

If you request information about a namespace to which you do not have access, HCP returns an HTTP 401 (Unauthorized) error code.

Example: Listing retention classes for a namespace

Here’s a sample HTTP GET request that retrieves XML describing the retention classes defined for the finance namespace owned by the europe tenant in the hcp.example.com system. The example saves the results in a file named finance.europe.retentionclasses.xml.

Request with curl command line

curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/proc/retentionClasses" >
    finance.europe.retentionclasses.xml

Request in Python using PycURL

import pycurl
filehandle = open("finance.europe.retentionclasses.xml", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /proc/retentionClasses")
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 /proc/retentionClasses HTTP/1.1
Host: /finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-Time: 1334326410
Content-Length: 1186

Response body

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/static/xsl/proc-retention-classes.xsl"?>
<retentionClasses xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="/static/xsd/proc-retention-classes.xsd"
        namespaceName="finance">
    <retentionClass
        name="Temporary"
        value="0"
        autoDelete="false">
        <description><![CDATA[
            Can be deleted at any time.
        ]]></description>
    </retentionClass>
    <retentionClass
        name="KeepForever"
       value="-1"
        autoDelete="false">
         <description><![CDATA[
            Deletion is permanently disallowed.
        ]]></description>
    </retentionClass>
    <retentionClass
        name="SecReg-107"
        value="A+21y"
        autoDelete="true">
        <description><![CDATA[
            Meets securities information rule 107 for retention of 21 years.
        ]]></description>
    </retentionClass>
    <retentionClass
        name="SevenYears"
        value="A+7y"
        autoDelete="true">
        <description><![CDATA[
            Object can be deleted after seven years.
        ]]></description>
    </retentionClass>
</retentionClasses>

Listing namespace and user permissions

You use the HTTP GET method to list the permissions for a namespace and the user making the request.

Request header

GET /proc/permissions HTTP/1.1

Response headers

This operation does not return any request-specific response headers.

Response body

namespacePermissions
The permissions specified for the namespace.
namespaceEffectivePermissions
The permissions that are in effect for the namespace. This is the logical AND of the permissions specified at the system, tenant, and namespace levels.
userPermissions
Your user permissions.
userEffectivePermissions
The permissions that result from the combination of the namespace permissions and your user permissions. This is the logical AND of the permissions specified for the system, tenant, and namespace and your user permissions.

Status codes

If you request information about a namespace to which you do not have access, HCP returns an HTTP 401 (Unauthorized) error code.

Example: Listing permissions for a namespace and user

Here’s a sample HTTP GET request that retrieves namespace and user permissions for:

The finance namespace owned by the europe tenant in the hcp.example.com system.
The pdgrey user account. (The account is identified by the Authorization header).

Request with curl command line

curl -k -H "Authorization: HCP cGRncmV5:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/proc/permissions"

Request in Python using PycURL

import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  cGRncmV5:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /proc/permissions")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

GET /proc/permissions HTTP/1.1
Host: /finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Content-Length: 1286

Response headers

HTTP/1.1 200 OK
X-HCP-Time: 1334326410
Content-Length: 880

Response body

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/static/xsl/proc-permissions.xsl"?>
<permissions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="/static/xsd/proc-permissions.xsd"
            namespaceName="finance">
    <namespacePermissions
        browse="true"
        read="true"
        write="true"
        changeOwner="true"
        delete="true"
        privileged="true"
        purge="true"
        search="false"/>
    <namespaceEffectivePermissions
        browse="true"
        read="true"
        write="true"
        changeOwner="true"
        delete="true"
        privileged="true"
        purge="false"
        search="false"/>
    <userPermissions
        browse="true"
        read="true"
        write="true"
        changeOwner="true"
        delete="true"
        privileged="false"
        purge="true"
        search="true"/>
    <userEffectivePermissions
        browse="true"
        read="true"
        write="true"
        changeOwner="true"
        delete="true"
        privileged="false"
        purge="false"
        search="false"/>
</permissions>

Listing namespace statistics

You use the HTTP GET method to list statistics for a namespace. The values returned include information such as the total and used capacity of the namespace and the number of objects with annotations.

Request header

GET /proc/statistics HTTP/1.1

Response headers

This operation does not return any request-specific response headers.

Response body

namespaceName
The namespace name.
totalCapacityBytes
The number of bytes of storage allocated to the namespace. This is the total space available for all data stored in the namespace, including object data, metadata, and the redundant data required to satisfy the namespace DPL.
usedCapacityBytes
The number of bytes currently occupied by all data stored in the namespace, including object data, metadata, and any redundant data required to satisfy the namespace DPL.
softQuotaPercent
The percent of the totalCapacityBytes value at which HCP notifies the tenant that free storage space for the namespace is running low.
objectCount
The number of objects, including old versions of objects, stored in the namespace.
The object count includes versions of objects that were deleted, but not delete markers. For example, if you create an object, add a version, delete the object while versioning is enabled but without specifying a version ID, and then add a new version of the object, the object count increases by three.
shredObjectCount
The number of objects and versions that have been deleted and are waiting to be shredded.
shredObjectBytes
The number of bytes occupied by the objects and versions that are waiting to be shredded.
customMetadataObjectCount
The number of objects and versions that have one or more annotations.
customMetadataObjectBytes
The number of bytes occupied by custom metadata in all annotations for all objects.

Status codes

If you request information about a namespace to which you do not have access, HCP returns an HTTP 401 (Unauthorized) error code.

Example: Listing statistics for a namespace

Here’s a sample HTTP GET request that retrieves statistics for the finance namespace owned by the europe tenant in the hcp.example.com system.

Request with curl command line

curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/proc/statistics"

Request in Python using PycURL

import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /proc/statistics")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()

Request headers

GET /proc/statistics HTTP/1.1
Host: /finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Content-Length: 1286

Response headers

HTTP/1.1 200 OK
X-HCP-Time: 1334326410
Content-Length: 565

Response body

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/static/xsl/proc-statistics.xsl"?>
<statistics xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="/static/xsd/proc-statistics.xsd"
    namespaceName="finance"
    totalCapacity="10737418240"
    usedCapacity="932454739"
    softQuota="85"
    objectCount="43230"
    shredObjectCount="0"
    shredObjectBytes="0"
    customMetadataObjectCount="6754"
    customMetadataObjectBytes="894893"
/>

REST API usage considerations

Data chunking with write operations

In some cases, the size of the data to be stored cannot be known at the start of a REST API PUT request. For example, the size is unknown if data is dynamically generated and the PUT request starts before all data is available. This scenario would occur if you do not have enough memory or disk space to stage dynamically generated data locally, so the application streams the PUT request as the data is generated.

In such cases, you can send the data using chunked HTTP transfer coding. Each chunk is sent with a known size, except for the last chunk, which is sent with a size of 0 (zero).

If possible, you should avoid chunking data because it increases the overhead required for the PUT operation.

Using the REST API with objects open for write

These considerations apply to using the REST API with an object that is open for write:

If you try to write to the object:
- If the namespace supports versioning, HCP creates a new version of the object.
- If the namespace does not support versioning, HCP returns an HTTP 409 (Conflict) error code and does not perform the operation.
If you try to retrieve, check the existence of, or copy the object:
- If the namespace supports versioning:
  - If the request does not specify a version ID and the object has one or more old versions, HCP performs the requested operation against the most recent version that is not open for write. However, if that version is a delete marker, HCP returns an HTTP 404 (Not Found) error code and does not perform the operation.
  - If the request does not specify a version ID and the object doesn’t have any old versions, HCP returns an HTTP 404 (Not Found) error code and does not perform the requested operation.
- If the namespace does not support versioning, HCP returns an HTTP 404 (Not Found) error code and does not perform the operation.
If you try to delete the object, HCP returns an HTTP 404 (Not Found) error code and does not delete the object.

NoteDepending on the timing, the delete request may result in a busy error. In that case, wait one or two seconds and then try the request again.

Failed REST API write operations

A write operation is considered to have failed if either of these is true:

The target node failed while the object was open for write.
The TCP connection broke while the object was open for write (for example, due to a network failure or the abnormal termination of the client application).

Also, in some circumstances, a write operation is considered to have failed if system hardware failed while the object was open for write.

If a write fails, HCP does not create a new object or version.

TipIf a write operations fails, retry the request.

Storing zero-sized files with the REST API

When you store a zero-sized file with the REST API, the resulting object has no data. Because the REST API causes a flush and a close even when no data is present, this object is WORM and is treated like any other object in the namespace.

Persistent connections with the REST API

HCP supports persistent connections with the REST API. Following a request for an operation, HCP keeps the connection open for 60 seconds, so a subsequent request can use the same connection.

Persistent connections enhance performance because they avoid the overhead of opening and closing multiple connections. In conjunction with persistent connections, using multiple threads so that operations can run concurrently provides still better performance.

If the persistent connection timeout period is too short, ask your tenant administrator about having it changed.

NoteWith persistent connections, if a single IP address has more than 254 concurrent open connections, those above the first 254 may have to wait as long as ten minutes to be serviced. This includes connections where the request explicitly targeted the IP address, as well as connections where the HCP hostname resolved to the target IP address.

To avoid this issue, either don’t use persistent connections or ensure that no more than 254 threads are working against a single node at any time.

Connection failure handling

You should retry a REST API request if either of these happens:

The client cannot establish an HTTP connection to the HCP system.
The connection breaks while HCP is processing a request. In this case, the most likely cause is that the node processing the request became unavailable.

When retrying the request:

If the original request used the hostname of the HCP system in the URL, repeat the request in the same way.
If the original request used an IP address, retry the request using either a different IP address or the hostname of the system.

If the connection breaks while HCP is processing a GET request, you may not know whether the returned data is all or only some of the object data. In this case, you can check the number of returned bytes against the content length returned in the HTTP Content-Length response header. If the numbers match, the returned data is complete.

Multithreading with the REST API

HCP lets multiple threads access a namespace simultaneously. Using multiple threads can enhance performance, especially when accessing many small objects across multiple directories.

HCP has a limit of 255 concurrent HTTP connections per node, with another 20 queued.

The REST, S3 compatible, and WebDAV APIs share the same connection pool.

TipFor better performance, consider limiting the number of concurrent read threads per node to 200 and concurrent write threads per node to 50 for small objects. For large objects, consider using fewer threads.

HTTP 500 and 503 status code considerations

When HCP returns an HTTP 500 (Internal Server Error) or 503 (Service Unavailable) error code, applications should try the request again. If necessary, retry the request multiple times with a gradually increasing delay between each attempt.

Session cookie encoding

In the response to a client request, HCP includes a cookie that contains encoded session information.

HCP supports two formats for encoding the session cookie:

RFC2109
HCP used only this format in releases 5.0 and earlier.
RFC6265
HCP has used this format by default in all releases since 5.0.

You can use the X-HCP-CookieCompatibility request header to specify the format HCP should use to encode the session cookie. Valid values for this header are RFC2109 and RFC6265.

The X-HCP-CookieCompatibility header is:

Optional and typically not used for RFC6265
Required for RFC2109

Quick Links

Accessing a namespace with the REST API

URLs for namespace access using the REST API

URL formats

Using an IP address in a URL

URL considerations

Authenticating namespace access

HCP authentication through the REST API

Authentication token

Authorization header

Active Directory user authentication through the REST API

Active Directory authentication token

Active Directory authorization header

Transmitting data in compressed format

Responding system

Working with objects and versions

Storing an object or version of an object

Copying an object or version of an object

Checking the existence of an object or multiple versions of an object

Listing object versions

Retrieving an object or multiple versions of an object

Deleting an object or object versions and using privileged delete

Purging an object and using privileged purge

Conditional operations

Working with directories

Creating an empty directory

Checking the existence of a directory

Listing directory contents

Deleting an empty directory

Working with system metadata

Specifying metadata on object creation

Modifying object metadata

Working with annotations

Storing an annotation

Checking the existence of an annotation

Listing annotations for an object or version

Retrieving annotations for objects and versions

Deleting annotations

Working with ACLs

Storing an ACL

Checking the existence of an ACL

Retrieving ACLs for objects and versions

Deleting an ACL

Retrieving namespace information

Listing accessible namespaces

Retrieving settings for an individual namespace

Listing retention classes

Listing namespace and user permissions

Listing namespace statistics

REST API usage considerations

Data chunking with write operations

Using the REST API with objects open for write

Failed REST API write operations

Storing zero-sized files with the REST API

Persistent connections with the REST API

Connection failure handling

Multithreading with the REST API

HTTP 500 and 503 status code considerations

Session cookie encoding