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) return code indicates that the requested object or object versions exist. An HTTP 404 (Not Found) return 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:
These rules apply to the
|
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 |
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
andX-HCP-ChangeTimeString
headers, but in a format that can be used directly inIf-Modified-Since
andIf-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
orfalse
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
orfalse
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
istrue
.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 theX-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
orfalse
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
orfalse
value indicating whether the object, has been replicated. The value istrue
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 offalse
. - The request includes the
X-HCP-Get-Replicated
header with a value oftrue
.
- HCP is configured to return this header, and the request does not include the
X-HCP-ReplicationCollision
A
true
orfalse
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
orfalse
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
- A date and time in this format:
X-HCP-Shred
A
true
orfalse
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 alwaysfalse
.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.
Return codes
The following table describes the HTTP return 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:
|
400 | Bad Request |
The request was not valid. These are some, but not all, of the possible reasons:
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:
|
412 | Precondition Failed |
One of:
|
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