HTTP methods

The table below provides a quick reference to the HTTP methods you use to access a namespace.

Method Summary/Permissions Elements Return codes/HCP-specific headers

DELETE

Summary

Deletes:

Objects

Versions (purge)

Empty directories

Annotations

ACLs

Symbolic links

Permissions

For all operations, delete

For purge, purge

For privileged operations, privileged

For all operations:

oAuthorization header or hcp-ns-auth cookie

oObject, 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

Return codes

Success: 200, 204

Error: 400, 403, 404, 409, 414, 500, 503

Response headers

  X-HCP-Time
  X-HCP-ServicedBy
System
  X-HCP-ErrorMessage
(if an error occurred
and more information
is available)

GET, except for name-space infor-mation re-quests

Summary

Retrieves:

Objects

Versions

Annotations

ACLs

Lists:

Versions

Directories

Annotations

Permission

For object, version, and annotation operations, read

To retrieve directory listings, browse

To retrieve ACLs, read ACL

For all operations:

oAuthorization header or hcp-ns-auth cookie

oObject, 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:

oThis URL query parameter:

type=whole-object

oTo control the order of the returned information, an X-HCP-Custom
MetadataFirst request header with a value of true or false (the default)

For objects and versions, optionally, an HTTP Range header specifying any of these zero-indexed byte ranges:

ostart-positionend-position

ostart-position

ooffset-from-end

Return codes

Success: 200, 206,

Error: 314, 400, 403, 404, 406, 412, 414, 416, 500, 503

Response headers

  X-HCP-Time
  X-HCP-SoftwareVersion
  X-HCP-ServicedBy
System
  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
  X-HCP-Index
  X-HCP-IngestProtocol
  X-HCP-IngestTime
  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

GET, except for name-space infor-mation re-quests
(Cont.)

 

To conditionally retrieve an object or version, these headers:

oIf-Match: ETag-list or *

oIf-None-Match: ETag-list or *

oIf-Modified-Since: datetime

oIf-None-Modified-
Since:
datetime

To force HCP to generate an ETag if the object does not yet have one:

forceEtag=true

To have change times for subdirectories in a directory listing reflect object additions and deletions, this URLquery 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)

Objects and versions (Cont.)
  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

GET of name-space infor-mation

Summary

Retrieves:

Namespace list

Namespace settings

Namespace retention classes

Namespace and user permissions

Namespace statistics

Permission

Any

For all operations:

oAuthorization header or hcp-ns-auth cookie

oNamespace 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

Return codes

Success: 200

Error: 400, 401, 403, 404, 414, 500, 503

Response headers

  X-HCP-Time
  X-HCP-ErrorMessage
(if an error occurred
and more information
is available)

HEAD

Summary

Checks existence of:

Objects

Versions

Directories

Annotations

ACLs

Retrieves metadata for:

Objects

Versions

Permission

For all operations, read

To check existence of ACLs, read or read ACL

For all operations:

oAuthorization header or hcp-ns-auth cookie

oObject, directory, or symbolic link URL

To conditionally check the existence of an object or version, these headers:

oIf-Match: ETag-list or *

oIf-None-Match: ETag-list or *

oIf-Modified-Since: datetime

oIf-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, this URL query parameter:

type=custom-metadata

annotation=annotation-name

The annotation name is optional for the default annotation.

To check ACLs, this URL query parameter:

type=acl

 

Return codes

Success: 200, 204

Error: 304, 400, 403, 404, 412, 414, 500, 503

Response headers

  X-HCP-Time
  X-HCP-SoftwareVersion
  X-HCP-ServicedBy
System
  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-ChangeTime
Milliseconds
  X-HCP-ChangeTime
String

Objects, versions, and annotations:
  ETag

Objects and versions:
  X-HCP-ACL
  X-HCP- CurrentStorageNode
  X-HCP-Custom-
Metadata
  X-HCP-Custom
MetadataAnnotations
  X-HCP-Domain
  X-HCP-DPL
  X-HCP-GID
  X-HCP-Hash
  X-HCP-Index
  X-HCP-IngestProtocol
  X-HCP-IngestTime
  X-HCP-Owner
  X-HCP-Replicated
  X-HCP-Retention
  X-HCP-RetentionClass
  X-HCP-RetentionHold
  X-HCP-RetentionString

HEAD
(Cont.)

   

Objects and versions (Cont.)
  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

POST

Summary

Changes one or more of these metadata values:

Hold status

Index setting

Retention setting

Shred setting

Object owner

Permission

For all operations, write

For hold, privileged

For owner, change owner

Authorization header or hcp-ns-auth cookie

Object URL

A body containing these form-encoded values:

oTo hold or release, this URL query parameter:

 hold=true|false

oTo change the index setting, this URL query parameter:

 index=true|false

oTo change the retention setting, this URL query parameter:

 retention=retention-
expression

oTo specify that the object will be shredded, this URL query parameter:

shred=true

oTo change the owner of the object, this URL query parameter:

 owner=user-name

oIf the owner query parameter specifies an Active Directory user, this URL query parameter:

 domain=AD-domain

Return codes

Success: 200

Error: 400, 403, 404, 414, 500, 503

Response headers

  X-HCP-ServicedBy
System
  X-HCP-ErrorMessage
(if an error occurred
and more information
is available)

PUT

Summary

Stores:

Objects

Versions

Empty directories

Annotations

ACLs

Copies objects

Permission

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:

oAuthorization header or hcp-ns-auth cookie

oObject or directory URL

For all operations except directory creation:

oA body containing the data

oTo send gzip-compressed data, a Content-Encoding request header with a value of gzip and a chunked transfer encoding

To copy an object, this header:

X-HCP-CopySource: source-namespace-name.source-tenant-name/object-path

Optionally, to control whether custom metadata is copied with object data, this header:

X-HCP-MetadataDirective: ALL | NONE (the default)

To copy a specific version of an object, this URL query parameter:

oversion=version-number

To conditionally store or copy an object, these headers:

oIf-Match: ETag-list or *

oIf-None-Match: ETag-list or *

oIf-Modified-Since: datetime

oIf-None-Modified-
Since:
datetime

To conditionally copy an object, these headers:

oX-HCP-CopySource-If-Match: ETag-list or *

oX-HCP-CopySource-If-None-Match: ETag-list or *

oX-HCP-CopySource-If-Modified-Since: datetime

oX-HCP-CopySource-If-None-Modified-Since: datetime

Return codes

Success: 201, 204

Error: 304, 400, 403, 404, 409, 412, 413, 414, 415, 500, 503

Response headers

  X-HCP-Time
  X-HCP-ServicedBy
System
  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

 

PUT
(Cont.)

 

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:

oThis URL query parameter:

type=whole-object

oAn 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 (the default)

To add a predefined ACL when storing an object or version, one of these URL query parameters:

oacl=all_read

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

 

Trademarks and Legal Disclaimer

© 2016 Hitachi Data Systems Corporation. All rights reserved.