HTTP reference
This section of the Help contains a reference of the HTTP methods available for accessing a namespace and the possible return codes and HCP-specific response headers.
HTTP methods
DELETE
Deletes:
- Objects
- Versions (purge)
- Annotations
- Empty directories
- ACLs
- Symbolic links
For all operations: delete
For purge: purge
For privileged operations: privileged
For all operations:
Authorization
header- Object, directory, or symbolic link URL
For privileged operations, these as URL query parameters or form-encoded data:
privileged=true reason=reason-text
To purge all versions, this as a URL query parameter or form-encoded data:
purge=true
To delete an annotation, these as URL query parameters:
type=custom-metadata annotation=annotation-name
The annotation name is optional for the default annotation.
To delete an ACL, this as a URL query parameter:
type=acl
X-HCP-Time
X-HCP-ServicedBySystem
X-HCP-ErrorMessage
(if an error occurred and more information is available)
Success: 200, 204
Error: 400, 403, 404, 409, 414, 500, 503
GET, except for namespace information requests
Retrieves:
- Objects
- Versions
- Annotations
- ACLs
Lists:
- Versions
- Directories
- Annotations
For object, version, and annotation operations: read
To retrieve directory listings: browse
To retrieve ACLs: read ACL
For all operations:
Authorization
header- Object, directory, or symbolic link URL
To retrieve data in Gzip format, an Accept-Encoding
header that contains gzip
or *
.
To retrieve a specific version, an annotation or ACL for a specific version, or list annotations for a specific version, this URL query parameter:
version=version-id
To retrieve a version list, this URL query parameter:
version=list
To list deleted objects or versions, this URL query parameter:
deleted=true
To choose not to wait for delayed retrievals, this URL query parameter:
nowait
To retrieve object or version data and an annotation together:
- This URL query parameter:
type=whole-object
- To control the order of the returned information, an
X-HCP-CustomMetadataFirst
request header with a value oftrue
orfalse
(the default)
To retrieve part of an object or version, an HTTP Range
header specifying any of these zero-indexed byte ranges:
- start-position-end-position
- start-position-
- -offset-from-end
To conditionally retrieve an object or version, these headers:
If-Match: etag-list
If-None-Match: etag-list
If-Modified-Since: datetime
If-None-Modified-Since: datetime
To force HCP to generate an ETag if the object does not yet have one:
forceEtag=true
To include or exclude the X-HCP-Replicated
header in the response, this header:
X-HCP-Get-Replicated: true|false
To have change times for subdirectories in a directory listing reflect object additions and deletions, this URL query parameter:
mostRecentDirTimes=true
To retrieve an annotation, these as URL query parameters:
type=custom-metadata annotation=annotation-name
The annotation name is optional for the default annotation.
To list annotations, this URL query parameter:
type=custom-metadata-info
To retrieve only an ACL, this URL query parameter:
type=acl
Optionally, to specify the format for the returned ACL, a Content-Type
header with one of:
application/json application/xml (the default)
Standard
X-HCP-Time
X-HCP-SoftwareVersion
X-HCP-ServicedBySystem
X-HCP-SymlinkTarget
(if URL is a symbolic link)
X-HCP-ErrorMessage
(if an error occurred and more information is available)
Objects, versions, directory listings, and annotations:
X-HCP-ChangeTime Milliseconds
X-HCP-ChangeTime String
Objects, versions, and annotations:
ETag
Objects and versions:
- Last-Modified
X-HCP-ACL
X-HCP-Custom-Metadata
X-HCP-Domain
X-HCP-DPL
X-HCP-GID
X-HCP-Hash
(not returned for multipart objects)
X-HCP-Index
X-HCP-IngestProtocol
X-HCP-IngestTime
X-HCP-LabelRetentionHold
X-HCP-LabelRetentionHold-Labels
X-HCP-Owner
X-HCP-Replicated
X-HCP-Retention
X-HCP-RetentionClass
X-HCP-RetentionHold
X-HCP-RetentionString
X-HCP-Shred
X-HCP-Size
X-HCP-Type
X-HCP-UID
X-HCP-VersionID
Partial objects and versions:
Content-Range
Objects and versions with annotations:
X-HCP-CustomMetadata Annotations
X-HCP-CustomMetadata ContentType
X-HCP-CustomMetadata First
X-HCP-DataContentType
Annotations:
X-HCP-ContentLength
X-HCP-Hash
X-HCP-Size
If response is in Gzip compressed format:
Content-Encoding
X-HCP-ContentLength
Directory listings:
X-HCP-Type
Success: 200, 206
Error: 314, 400, 403, 404, 406, 412, 414, 416, 500, 503
GET of namespace information
Retrieves:
- Namespace list
- Namespace settings
- Namespace retention classes
- Namespace and user permissions
- Namespace statistics
Any
For all operations:
Authorization
header- Namespace information URL
To retrieve a namespace list:
http[s]://namespace.tenant.domain/proc
To retrieve settings for an individual namespace:
http[s]://namespace.tenant.domain/proc?single=true
To retrieve retention classes:
http[s]://namespace.tenant.domain/proc/retentionClasses
To retrieve permissions:
http[s]://namespace.tenant.domain/proc/permissions
To retrieve statistics:
http[s]://namespace.tenant.domain/proc/statistics
X-HCP-Time
X-HCP-ErrorMessage
(if an error occurred and more information is available)
Success: 200
Error: 400, 401, 403, 404, 414, 500, 503
HEAD
Checks existence of:
- Objects
- Versions
- Directories
- Annotations
- ACLs
Retrieves metadata for:
- Objects
- Versions
For all operations: read
To check existence of ACLs: read or read ACL
For all operations:
Authorization
header- Object, directory, or symbolic link URL
To conditionally check the existence of an object or version, these headers:
If-Match: etag-list
If-None-Match: etag-list
If-Modified-Since: datetime
If-None-Modified-Since: datetime
To check a specific version or the annotation for a specific version, this URL query parameter:
version=version-id
To check an annotation, these URL query parameters:
type=custom-metadata annotation=annotation-name
The annotation name is optional for the default annotation.
To check ACLs, this URL query parameter:
type=acl
To include or exclude the X-HCP-Replicated
header in the response, this header:
X-HCP-Get-Replicated: true|false
General
X-HCP-Time
X-HCP-SoftwareVersion
X-HCP-ServicedBySystem
X-HCP-SymlinkTarget
(if URL is a symbolic link)
X-HCP-ErrorMessage
(if an error occurred and more information is available)
Objects, versions, directories, and annotations:
-
X-HCP-ChangeTimeMilliseconds
X-HCP-ChangeTimeString
Objects, versions, and annotations:
ETag
Objects and versions:
X-HCP-ACL
X-HCP- CurrentStorageNode
X-HCP-Custom-Metadata
X-HCP-CustomMetadataAnnotations
X-HCP-Domain
X-HCP-DPL
X-HCP-GID
X-HCP-Hash
(not returned for multipart objects)
X-HCP-Index
X-HCP-IngestProtocol
X-HCP-IngestTime
X-HCP-LabelRetentionHold
X-HCP-LabelRetentionHold-Labels
X-HCP-Owner
X-HCP-Replicated
X-HCP-Retention
X-HCP-RetentionClass
X-HCP-RetentionHold
X-HCP-RetentionString
X-HCP-Shred
X-HCP-Size
X-HCP-Type
X-HCP-UID
X-HCP-VersionID
Directories:
X-HCP-Hash
X-HCP-Size
X-HCP-Type
ACLs:
X-HCP-ACL
Success: 200, 204
Error: 304, 400, 403, 404, 412, 414, 500, 503
POST
Changes one or more of these metadata values:
- Hold status
- Index setting
- Retention setting
- Shred setting
- Object owner
For all operations: write
For hold: privileged
For owner: change owner
Authorization
header- Object URL
- A body containing these form-encoded values:
- To hold or release, this URL query parameter:
hold=true|false
- To change the index setting, this URL query parameter:
index=true|false
- To change the retention setting, this URL query parameter:
retention=retention-expression
- To add or change a labeled retention hold, this query parameter:
label_hold = [{"id":"UniqueLabelHold-1","hold":true|false}, {"id":"UniqueLabelHold-2","hold":true|false}]
- To specify that the object will be shredded, this URL query parameter:
shred=true
- To change the owner of the object, this URL query parameter:
owner=user-name
- If the owner query parameter specifies an Active Directory user, this URL query parameter:
domain=ad-domain
- To hold or release, this URL query parameter:
X-HCP-ServicedBySystem
X-HCP-ErrorMessage
(if an error occurred and more information is available)
Success: 200
Error: 400, 403, 404, 414, 500, 503
PUT
Stores:
- Objects
- Versions
- Empty directories
- Annotations
- ACLs
Copies objects
For all operations: write
To copy objects and versions: read for source namespace
To hold or release: privileged
To add an ACL: write or write ACL
For all operations:
Authorization
header- Object or directory URL
For all operations except directory creation:
- A body containing the data
- To send Gzip compressed data, a
Content-Encoding
request header with a value ofgzip
and a chunked transfer encoding
To copy an object, this header:
X-HCP-CopySource:source-namespace-name.source-tenant-name/object-path
To add or change a labeled retention hold, this query parameter:
label_hold = [{"id":"UniqueLabelHold-1","hold":true|false}, {"id":"UniqueLabelHold-2","hold":true|false}]
Optionally, to control whether custom metadata is copied with object data, this header:
X-HCP-MetadataDirective:ALL|NONE
Default is NONE
.
To copy a specific version of an object, this URL query parameter:
version=version-number
To conditionally store or copy an object, these headers:
If-Match: etag-list
If-None-Match: etag-list
If-Modified-Since: datetime
If-None-Modified-Since: datetime
To conditionally copy an object, these headers:
X-HCP-CopySource-If-Match: etag-list
X-HCP-CopySource-If-None-Match: etag-list
X-HCP-CopySource-If-Modified-Since: datetime
X-HCP-CopySource-If-None-Modified-Since: datetime
For copy operations, to force HCP to generate an ETag if the source object does not yet have one:
forceEtag=true
To create a directory, this URL query parameter:
type=directory
To store an annotation, these as URL query parameters:
type=custom-metadata annotation=annotation-name
The annotation name is optional for the default annotation.
To store object or version data and an annotation together:
- This URL query parameter:
type=whole-object
- An
X-HCP-Size
request header with the size of the object, in bytes
To add an ACL to an existing object, this URL query parameter:
type=acl
Optionally, to specify the ACL format, a Content-Type
header with one of these values:
application/json application/xml (default value)
To add a predefined ACL when storing an object or version, one of these URL query parameters:
acl=all_read acl=auth_read
To set hold, index, retention, or shred metadata when storing an object or version, see the query parameters described for the POST method.
General
X-HCP-Time
X-HCP-ServicedBySystem
X-HCP-ErrorMessage
(if an error occurred and more information is available)
Storing or copying objects and versions:
ETag
X-HCP-Hash
X-HCP-VersionID
Storing or copying object or version data and an annotation together:
ETag
X-HCP-CustomMetadataHash
X-HCP-Hash
X-HCP-VersionID
Storing annotations:
X-HCP-Hash
Success: 201, 204
Error: 304, 400, 403, 404, 409, 412, 413, 414, 415, 500, 503
HTTP return codes
The table below describes the possible return codes for HTTP requests that access a namespace.
Code | Meaning | Methods | Description |
200 | OK |
DELETE GET HEAD POST |
HCP successfully processed a request that does any of:
Note: For a GET request for an object or version, if the number of bytes returned does not equal the value of the |
201 | Created | PUT | HCP successfully added an object, version, annotation, ACL, or directory to the namespace, copied an object, or replaced an annotation or ACL for an object. |
204 | No Content |
GET or HEAD of an annotation or a version GET of information about annotations DELETE of an annotation |
One of:
|
206 | Partial Content | GET with a Range header | HCP successfully retrieved the data in the byte range specified in the request. |
304 | Not Modified |
GET, PUT, or HEAD with If-Modified-Since GET or HEAD with If-None-Match PUT with X-HCP-Copy-Source-If-Modified-Since PUT with X-HCP-Copy-Source-If-None-Match |
One of:
|
400 | Bad Request | All |
The request was not valid. These are some, but not all, of the possible reasons:
If more information about the error is available, the response headers include the HCP-specific |
401 | Unauthorized | GET for namespace information | The user does not have access to the namespace for which information is being requested. |
403 | Forbidden | All |
The requested operation was not allowed. These are some, but not all, of the possible reasons:
If more information about the error is available, the response headers include the HCP-specific |
404 | Not Found |
DELETE GET HEAD POST PUT of an annotation or ACL GET of information about annotations |
One of:
|
406 | Not Acceptable | GET |
One of:
|
409 | Conflict |
DELETE PUT |
One of:
|
410 | Gone |
GET PUT with X-HCP-CopySource |
Possible reasons include:
|
412 | Precondition Failed |
GET, HEAD, or PUT with If-Match or If-Unmodified-Since header PUT with If-None-Match, X-HCP-Copy-Source-If-Match, or X-HCP-Copy-Source-If-Unmodified-Since header |
One of:
|
413 | File Too Large | PUT |
One of:
|
414 | Request URI Too Large | All | The portion of the URL following rest is longer than 4,095 bytes. |
415 | Unsupported Media Type | POST |
One of:
|
416 | Requested Range Not Satisfiable | GET with a Range header |
One of:
|
500 | Internal Server Error | All |
An internal error occurred. Try the request again, gradually increasing the delay between each successive attempt. If this error happens repeatedly, please contact your tenant administrator. |
503 | Service Unavailable | All |
One of:
In the last two cases, try the request again, gradually increasing the delay between each successive attempt. If the error persists, please contact your tenant administrator. If more information about the error is available, the response headers include the HCP-specific |
HTTP response headers specific to HCP
The next table describes the HTTP response headers specific to HCP.
Header | Methods | Description |
X-HCP-ACL |
HEAD for an object, version, or ACLs GET for objects and object versions | A true or false value indicating whether the object has an ACL. |
X-HCP-ChangeTimeMilliseconds | GET or HEAD for an object, version, or annotation | The change time for the object or annotation, in milliseconds since January 1, 1970, at 00:00:00 UTC, followed by an integer that’s unique for the change time |
X-HCP-ChangeTimeString | GET or HEAD for objects, object versions, and annotations |
The change time for the object or annotation, in this format: yyyy-MM-ddThh:mm:ssZ In this format, Z represents the offset from UTC and is specified as: (+|-)hhmm |
X-HCP-ContentLength | GET with compressed transmission | The length of the returned data before HCP compressed it. |
X-HCP-CurrentStorageNode | HEAD for an object or object version |
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 hostname in the request URL. This header is returned only if both of these are true:
|
X-HCP-Custom-Metadata | GET or HEAD for an object or object version | A true or false value indicating whether the object has any annotations. |
X-HCP-CustomMetadataAnnotations | GET or HEAD for an object or object version |
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, as in report_data;12908. This header is returned only if |
X-HCP-CustomMetadataContentType | GET or HEAD for an object or version data and an annotation together |
The custom metadata type, one of:
|
X-HCP-CustomMetadataFirst | GET for an object or version data and an annotation together |
One of:
|
X-HCP-CustomMetadataHash | PUT for object data and an annotation together |
The cryptographic hash algorithm HCP uses and the cryptographic hash value of the stored annotation, in this format:
You can use the returned hash value to verify that the stored annotation is the same as the custom metadata you sent. To do this, compare this value with a hash value that you generate from the original custom metadata. |
X-HCP-DataContentType | GET for and object or version data and an annotation together |
The Internet media type of the object, such as |
X-HCP-Domain | GET or HEAD for an object or version |
The Active Directory domain that contains the user account identified by the This value is an empty string if the If the |
X-HCP-DPL | GET or HEAD for an object or version | The data protection level of the object or version. |
X‑HCP-ErrorMessage | All |
Detailed information about the cause of an error. This header is returned only if a request results in a 400, 403, or 503 error code and HCP has specific information about the cause. |
X-HCP-GID | GET or HEAD for an object or version |
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 are true:
|
X-HCP-Hash |
HEAD and GET for an object, version, or annotation PUT for an object or annotation |
The cryptographic hash algorithm the namespace uses, along with a cryptographic hash value of the stored object or annotation:
You can use the returned hash value to verify that the stored data is the same as the data you sent. To do this, compare this value with a hash value that you generate from the original data. The |
X-HCP-Index | HEAD and GET for objects and object versions | A true or false value indicating whether the object is marked for indexing. |
X-HCP-IngestProtocol | HEAD and GET for objects and object versions |
The namespace access protocol through which the object was added to the namespace. One of:
If HCP cannot determine the protocol through which the object was added, this value is |
X-HCP-IngestTime | HEAD and GET for objects and object versions | The time when HCP stored the object, in seconds since January 1, 1970, at 00:00:00 UTC. |
X-HCP-LabelRetentionHold | HEAD and GET for objects | A Boolean value (true |false ) indicating whether the object is on labeled hold. |
X-HCP-LabelRetentionHold-Labels | HEAD and GET for objects |
If the object is on labeled hold ( Example X-HCP-LabelRetentionHold-Labels: [{"id":"UniqueLabelHold-1","hold":true}, {"id":"UniqueLabelHold-2","hold":true}, {"id":"UniqueLabelHold-3","hold":true}] |
X-HCP-Owner | HEAD and GET for objects and object versions |
The user that owns the object. This value can be one of:
|
X-HCP-Replicated | HEAD and GET for objects and object versions |
A HCP returns this header only if either of these is true:
|
X-HCP-ReplicationCollision | HEAD and GET for objects and object versions | A true or false value indicating whether the object is flagged as a replication collision. |
X-HCP-Retention | HEAD and GET for objects and object versions | The end of the retention period for the object, in seconds since January 1, 1970, at 00:00:00 UTC. This value can also be 0 , -1 , or -2 . |
X-HCP-RetentionClass | HEAD and GET for objects and object versions | 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 | HEAD and GET for objects and object versions | A true or false value indicating whether the object is on hold. |
X-HCP-RetentionString | HEAD and GET for objects and object versions |
The end of the retention period 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, 2015-11-16T14:27:20-0500 represents the start of the 20th second into 2:27 PM, November 16, 2015, EST. The value can also be |
X-HCP-ServicedBySystem | All except GET for namespace information |
The domain name of the HCP system responding to the request. If the target HCP system is unable to respond to the request and also participates in replication, this value may be another system in the replication topology. |
X-HCP-Shred | HEAD and GET for objects and object versions | A true or false value indicating whether HCP will shred the object after it is deleted. |
X-HCP-Size | HEAD and GET for objects, object versions, and annotations | The size of the object, version, or annotation, in bytes. For whole-object data, this value is the size of the object data. |
X-HCP-SoftwareVersion | HEAD and GET for objects, object versions, annotations, ACLs, and directories | The version number of the HCP software. |
X-HCP-SymlinkTarget | HEAD and GET |
The path to the target object or directory as specified when the symbolic link was created. This header is returned only if the URL specifies a symbolic link to an object or directory. |
X-HCP-Time | All except POST | The time at which HCP sent the response to the request, in seconds since January 1, 1970, at 00:00:00 UTC. |
X-HCP-Type | HEAD and GET for objects, object versions, annotations, and directories |
The entity type. One of:
|
X-HCP-UID | HEAD and GET for objects and object versions |
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 are true:
|
X-HCP-VersionId |
HEAD and GET for objects and object versions PUT for objects and object versions | The version ID of the object. |
Common HTTP response headers
HTTP requests return some common response headers that address browser security concerns. The next table describes some of these common headers.
Header | Value | Description |
Cache-Control |
| Specifies directives that must be obeyed by all caching mechanisms along the request/response chain |
Content-Security- Policy |
| Restricts the content that the browser can load to the sources specified by the header value |
Expires | Thu, 01 Jan 1970 00:00:00 GMT | Causes the response to become stale immediately after it is sent |
Pragma | no-cache | Prevents the response from being used for subsequent requests for the same resource without the browser first checking whether the resource has changed |
X-Content-Type- Options | nosniff | Prevents the browser from examining the returned content to determine the content MIME type |
X-DNS-Prefetch- Control | off | Prevents the browser from performing domain name resolution on URLs embedded in returned content before the URLs are requested |
X-Download- Options | noopen | Prevents the browser from opening resources that are downloaded through links in the returned content |
X-Frame-Options | SAMEORIGIN | Prevents the browser from rendering the returned content in a frame on a page containing content not returned by the HCP system |
X-XSS-Protection | 1 ; mode=block | Stops the browser from loading the returned content if the browser detects reflected cross-site scripting (XSS) in the response |
HCP can also return several standard HTTP response headers that are not described in the help, including Connection
, Content-Disposition
, Content-Encoding
, and Content-Language
. For more information about HTTP response headers, see the HTTP/1.1 standards, RFCs 7230 through 7237.