Retrieving an object or multiple versions of an object

Content Platform Tenant Management Help

Version
9.7.x
File Size
4269 KB
Audience
anonymous
Part Number
MK-95HCPH002-19

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.

Note: Attempts 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 records. To retrieve a listing that includes delete records, 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-positionend-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.

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
Tip: If 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