Skip to main content
Hitachi Vantara Knowledge

Working with objects

With the HSwift API, you can perform operation on individual objects.

For each object operation you can request, this chapter:

  • Describes the operation
  • Shows the request line for the operation
  • Describes the request headers for the operation
  • Describes the response headers returned for a successful execution of the request operation
  • Explains the HTTP status codes that can be returned in response to requests for the operation
  • Presents one or more examples of requests for the operation

Storing an object

You use the HTTP PUT method to store an object in a container. To store an object, you need the write permission for the container.

For a request to store an object, the request body consists of the data in a specified file. This data becomes the object content.

When you store an object, you specify a name for it. The object name does not need to be the same as the name of the file containing the original data.

If versioning is enabled and you try to store an object with the same name as an existing object, HCP stores both versions of the object, but HSwift can only access the newest version. If versioning is disabled and you try to store an object with the same name as an existing object, HCP returns a 409 (Conflict) status code and does not store the object.

You can add custom metadata to an object in the same request as you use to store the object. To do this, you use X-Object-Meta- headers.

Request line

Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to store an object has either of these formats:

  • With the Keystone tenant ID:
    PUT /swift/v1/tenant-ID/container-name/object-name HTTP/1.1
  • With the account name:
    PUT /swift/v1/account-name/container-name/object-name HTTP/1.1
Request headers

The table below describes the headers you can use in a request to store an object.

NameTypeDescription
X-Auth-TokenString

Used to supply the Keystone authentication token or local authentication token.

Replace the Keystone authentication token with the prefix HCP, followed by your Local Authentication token, in the format:

"X-Auth-Token: HCP base64-encoded-username:md5-encoded-password"

For example:

"X-Auth-Token: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
Content-EncodingStringSpecifies whether the request body is compressed. If so, enter gzip.
Content-LengthIntegerSpecifies the size, in bytes, of the data being stored.
EtagString

This value is the MD5 checksum of the object content.

It is recommended to compute the MD5 checksum of the file being uploaded and include the value in this header. HCP fails the transaction if the MD5 of the file received did not matched this value.

ExpectStringUse the Expect header with the value of 100-Continue in combination with the If-None-Match header with the value set to an asterisk (*) to query whether the server already has an object of the same name before any data is sent.
If-None-MatchString

Specifies one or more values for comparison with the ETag of the specified source object. If the ETag doesn't match any of the specified values, HCP continues processing the request. If the ETag matches any of the specified values, HCP returns a 412 (Precondition Failed) status code.

To specify the values for this header, use this format:

"value"[, "value"]...

In this format, each value can be any string of more characters and must be enclosed in double quotation marks (").

Alternatively, you can specify a single asterisk (*) as the value of the If-None-Match header. No ETags match an asterisk in an If-None-Match header.

Transfer-EncodingStringIf this header is used, always set to chunked. This header should be used if HCP cannot determine the size of the response body before formulating the response.
X-Copy-FromString

Specifies the source container and object in this format:

/container-name/source-object-name

You must UTF-8-encode and then URL-encode the names of the container and object before you include them in the header. Using X-Copy-From locates the source object to copy, and when it is used in conjecture with a PUT command X-Copy-From has the same effect as using the COPY operation to copy an object.

X-Object-Meta-nameStringFor objects only, specifies a custom metadata property/value pair. The response headers include one X-Object-Meta- header for each applicable pair.
Response headers

The table below describes the response headers returned in response to a successful request to store an object.

NameTypeDescription
Content-lengthString (Required)

The size, in bytes, of the response body if HCP can determine the size before formulating the response.

If the response does not include a response body, the value of the Content-Length is 0 (zero).

Content-TypeString (Required if the Content-Length is greater than 0)

The Internet media type of the response body if HCP can determine the Internet media type. If HCP cannot determine the Internet media type, the value of this header is application/octet-stream.

Because HCP returns error information in a response body, the response to any request can include a Content-Type header.

ETagString (Required)Contains the MD5 hash of the received file.
DateDatetime (Required)

The date and time at which HCP responded to the request in Greenwich Mean Time (GMT). The date and time are returned in this format:

DDD dd MMM yyyy HH:mm:ss GMT

For example:

Thu, 14 Mat 2013 14:27:05 GMT
X-Trans-IdUuid (Required)HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database.
HTTP status codes

The table below describes HTTP status codes that can be returned in response to a request to store an object.

CodeMeaningDescription
201CreatedThe object has been added to the container.
408Request TimeoutThe request has timed out and not completed. It is no longer trying to resend the request.
409ConflictThe object exists already and versioning is not enabled.
411Length RequiredIndicates a missing Transfer-Encoding or Content-Length request header.
412Precondition FailedIf using "If-None-Match: *" header and an object already exists at the specified path.
422Unprocessable EntityMD5 checksum of the data that is written to the object store does not match the optional ETag value.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

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: Storing an object

Here's a sample PUT request that stores an object named Q4_2012.ppt in the finance container.

Request with curl command line

curl -k -i -X PUT http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/Q4_2012.ppt -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87" -H "Content-Length: 63" -H "Etag: 61d952ad1d4bdb14aa221d046a6289de" -T Q4_2012.ppt

Request headers

PUT /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/Q4_2012.ppt HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87

Response headers

HTTP/1.1 201 Created
Date: Mon, 20 Oct 2014 20:48:36 GMT
ETag: "1774af03f76ef80fa0c08b9dbd8d19f9"
X-Trans-Id: txfe5244ce53a142288ef97-00541b3b32
Content-Type: application/octet-stream
Content-Length: 0

Creating a directory

You use the HTTP PUT method to create a directory in a container. To create a directory, you need write permission for the container.

To tell HCP to create a directory instead of an object in response to a PUT request, you need to include a forward slash (/) after the directory's name.

When you create a directory, you specify a name for it. The rules for directory names are the same as the rule for object names.

Request line

Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to create a directory has either of these formats:

  • With the Keystone tenant ID:
    PUT /swift/v1/tenant-ID/container-name/directory-name/ HTTP/1.1
  • With the account name:
    PUT /swift/v1/account-name/container-name/directory-name/ HTTP/1.1
Request headers

The table below describes the headers you can use in a request to create a directory.

NameTypeDescription
X-Auth-TokenString

Used to supply the Keystone authentication token or local authentication token.

Replace the Keystone authentication token with the prefix HCP, followed by your Local Authentication token, in the format:

"X-Auth-Token: HCP base64-encoded-username:md5-encoded-password"

For example:

"X-Auth-Token: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
Content-EncodingStringSpecifies whether the request body is compressed. If so, enter gzip.
Content-LengthIntegerSpecifies the size, in bytes, of the data being stored.
EtagString

This value is the MD5 checksum of the object content.

It is recommended to compute the MD5 checksum of the response body and compare this value with this ETag header. If they differ, the content may have been corrupted.

ExpectStringUse the Expect header with the value of 100-Continue in combination with the If-None-Match header with the value set to an asterisk (*) to query whether the server already has an object of the same name before any data is sent.
If-None-MatchString

Specifies one or more values for comparison with the ETag of the specified source object. If the ETag doesn't match any of the specified values, HCP continues processing the request. If the ETag matches any of the specified values, HCP returns a 412 (Precondition Failed) status code.

To specify the values for this header, use this format:

"value"[, "value"]...

In this format, each value can be any string of more characters and must be enclosed in double quotation marks (").

Alternatively, you can specify a single asterisk (*) as the value of the If-None-Match header. No ETags match an asterisk in an If-None-Match header.

Transfer-EncodingStringIf this header is used, always set to chunked. This header should be used if HCP cannot determine the size of the response body before formulating the response.
X-Copy-FromString

Specifies the source container and object in this format:

/container-name/source-directory-name

You must UTF-8-encode and then URL-encode the names of the container and object before you include them in the header. Using X-Copy-From locates the source object to copy, and when it is used in conjecture with a PUT command X-Copy-From has the same effect as using the COPY operation to copy an object.

Response headers

The table below describes the response headers returned in response to a successful request to create a directory.

NameTypeDescription
Content-lengthString (Required)

The size, in bytes, of the response body if HCP can determine the size before formulating the response.

If the response does not include a response body, the value of the Content-Length is 0 (zero).

Content-TypeString (Required if the Content-Length is greater than 0)

The Internet media type of the response body if HCP can determine the Internet media type. If HCP cannot determine the Internet media type, the value of this header is application/octet-stream.

Because HCP returns error information in a response body, the response to any request can include a Content-Type header.

ETagString (Required)Specifies the ETag for the object.
DateDatetime (Required)

The date and time at which HCP responded to the request in Greenwich Mean Time (GMT). The date and time are returned in this format:

DDD dd MMM yyyy HH:mm:ss GMT

For example:

Thu, 14 Mat 2013 14:27:05 GMT
X-Trans-IdUuid (Required)HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database.
HTTP status codes

The table below describes HTTP status codes that can be returned in response to a request to store an object.

CodeMeaningDescription
201CreatedThe object has been added to the container.
408Request TimeoutThe request has timed out and not completed. It is no longer trying to resent the request.
409ConflictThe object already exists and versioning is not enabled.
411Length RequiredIndicates a missing Transfer-Encoding or Content-Length request header.
412Precondition FailedIf using If-None-Match: * header and an object already exists at the specified path.
422Unprocessable EntityMD5 checksum of the data that is written to the object store does not match the optional ETag value.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

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: Creating a directory

Here's a sample PUT request that creates a directory named budget_proposals in the r&d directory in the finance container. If the r&d directory doesn't already exist, this request also creates that directory.

Request with curl command line

curl -k -i -X PUT http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/r&d/budget_proposals/ -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87"

Request headers

PUT /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/r&d/budget_proposals/ HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87

Response headers

HTTP/1.1 201 Created
Date: Fri, 24 Oct 2014 14:29:06 GMT
ETag: d41d8cd98f00b204e9800998ecf8427e
X-Trans-Id: txfe5244ce53a142288ef97-00541b3b32
Content-Type: application/octet-stream
Content-Length: 0

Checking the metadata of an object or directory

You use the HTTP HEAD method to check the metadata of an object or directory in a container. To check the metadata of an object or directory, you need read permission for the container containing the object or directory.

In response to a request to check the metadata of an object or directory, HCP returns a 200 (OK) status code if the object or directory exists and a 404 (Not Found) status code if the object or directory doesn't exist. If you don't have read permission for the container or object, HCP returns a 403 (Forbidden) status code.

Request line

Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to check the metadata of an object has either of these formats:

  • With the Keystone tenant ID:
    HEAD /swift/v1/tenant-ID/container-name/folder-name/object-name HTTP/1.1
  • With the account name:
    HEAD /swift/v1/account-name/container-name/folder-name/object-name HTTP/1.1

Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to check the metadata of a directory has either of these formats:

  • With the Keystone tenant ID:
    HEAD /swift/v1/tenant-ID-token/container-name/directory-name/ HTTP/1.1
  • With the account name:
    HEAD /swift/v1/account-name/container-name/directory-name/ HTTP/1.1
Request headers

The table below describes the headers you can use in a request to check the metadata of an object or directory.

NameTypeDescription
X-Auth-TokenString

Used to supply the Keystone authentication token or local authentication token.

Replace the Keystone authentication token with the prefix HCP, followed by your Local Authentication token, in the format:

"X-Auth-Token: HCP base64-encoded-username:md5-encoded-password"

For example:

"X-Auth-Token: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
Response headers

The table below describes the headers you can use in a request to check the metadata of an object or directory.

NameTypeDescription
Content-lengthString (Required)

The size, in bytes, of the response body if HCP can determine the size before formulating the response.

If the response does not include a response body, the value of the Content-Length is 0 (zero).

Content-TypeString (Required if the Content-Length is greater than 0)

The Internet media type of the response body if HCP can determine the Internet media type. If HCP cannot determine the Internet media type, the value of this header is application/octet-stream.

Because HCP returns error information in a response body, the response to any request can include a Content-Type header.

DateDatetime (Required)

The date and time at which HCP responded to the request in Greenwich Mean Time (GMT). The date and time are returned in this format:

DDD dd MMM yyyy HH:mm:ss GMT

For example:

Thu, 14 Mat 2013 14:27:05 GMT
ETagString (Required)This value is the MD5 checksum value of the object content.
Last-ModifiedString (Required)The date and time that the object was created or the last time that the metadata was modified.
X-Object-ManifestString

For multipart objects, specifies the name of the container in which the parts of the multipart object are stored, followed by the common prefix for the part names, in this format: container-name/prefix

This header is returned only for multipart objects.

X-Object-Meta-nameString (Required)For object, specifies a custom metadata property/value pair. The response headers include one X-Object-Meta-name header for each applicable pair.
X-Static-Large-ObjectStringAlways false. HCP does not support static large objects.
X-Trans-IdUuid (Required)HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database.
HTTP status codes

The table below describes HTTP status codes that can be returned in response to a request to check the metadata of an object or directory.

CodeMeaningDescription
200SuccessThe object data has been retrieved.
204Request TimeoutThe request has timed out and the operation was not completed. Hswift is no longer retrying the operation.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

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: Retrieving custom metadata for an object

Here's a sample HEAD request that checks the metadata of an object named sales_quotas_2013.pdf, which has custom metadata.

Request with curl command line

curl -k -i -X HEAD http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/sales_quotas_2013.pdf -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87"

Request headers

HEAD /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/sales_quotas_2013.pdf HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87
X-Object-Meta-author: P.D Grey

Response headers

HTTP/1.1 200 OK
Date: Fri, 24 Oct 2014 14:29:06 GMT
X-Trans-Id: 156263da-2e0c-49d6-b237-dc7745bd3975
Accept-Ranges: bytes
X-Static-Large-Object: false
ETag: d41d8cd98f00b204e9800998ecf8427e
Last-Modified: Fri, 31 Oct 2014 20:40:16 GMT
X-Object-Meta-author: P.D Grey
Content-Type: application/octet-stream
Content-Length: 0
Example: Checking the metadata of a directory

Here's a sample HEAD request that checks the metadata of a directory named r&d in the finance directory.

Request with curl command line

curl -k -i -X HEAD http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/r&d/ -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87"

Request headers

HEAD /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/r&d/ HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87

Response headers

HTTP/1.1 200 OK
Date: Fri, 31 Oct 2014 20:55:13 GMT
X-Trans-Id: 05c677f6-2044-412d-a9c6-850298b4971a
Accept-Ranges: bytes
X-Static-Large-Object: false
ETag: d41d8cd98f00b204e9800998ecf8427e
Last-Modified: Fri, 31 Oct 2014 20:10:44 GMT
Content-Type: application/octet-stream
Content-Length: 0

Copying an object

You use the HTTP COPY method with the Destination header to copy an object from one location to another. The source and target locations can be two different containers within the same tenant, or they can be the same container. The source object is the object you're copying. The target object is the object that results from the copy operation.

To copy an object, you need read permission for the container containing the source object or for the source object itself and write permission for the target container.

When copying an object, you can specify a name for the target object that's different from the name of the source object.

Regardless of whether or not versioning is enabled, only the latest version of a source object is taken for the copy.

By default, HCP copies custom metadata for the source object to the target object. However, in the copy request, you can specify additional custom metadata to be used for the target object. To apply this custom metadata to the target object, you need to include the X-Object-Meta-name header in the copy request.

NoteDepending on the replication configuration, copy operations may be slow and, for large objects, may time out.

If the target object you specify in a copy request identifies an existing object , HCP replaces the existing object with the new copy. If versioning is disabled the operation fails and a 409 (Conflict) HTTP status code appears.

Request line

Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to copy an object has either of these formats:

  • With the Keystone tenant ID:
    COPY /swift/v1/tenant-ID/container-name/directory-name/object-name HTTP/1.1
    "Destination: /container-name/object-name"
  • With the account name:
    COPY /swift/v1/account-name/container-name/directory-name/object-name HTTP/1.1
    "Destination: /container-name/object-name"
Request headers

The table below describes the headers you can use in a request to copy an object.

NameTypeDescription
X-Auth-TokenString

Used to supply the Keystone authentication token or local authentication token.

Replace the Keystone authentication token with the prefix HCP, followed by your Local Authentication token, in the format:

"X-Auth-Token: HCP base64-encoded-username:md5-encoded-password"

For example:

"X-Auth-Token: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
DestinationString (Required)

Specifies the destination of the copied container and object, in this format:

/container-name/source-object-name

The initial forward slash (/) is required.

You must UTF-8-encode and then URL-encode the names of the destination container and object before you include them in this header.

X-Object-Meta-nameStringFor objects only, specifies a custom metadata property/value pair. The response headers include one X-Object-Meta- header for each applicable pair.
Response headers

The table below describes the response headers returned in response to a successful request to copy an object.

NameTypeDescription
Content-lengthString (Required)

The size, in bytes, of the response body if HCP can determine the size before formulating the response.

If the response does not include a response body, the value of the Content-Length is 0 (zero).

Content-TypeString (Required if the Content-Length is greater than 0)

The Internet media type of the response body if HCP can determine the Internet media type. If HCP cannot determine the Internet media type, the value of this header is application/octet-stream.

Because HCP returns error information in a response body, the response to any request can include a Content-Type header.

DateDatetime (Required)

The date and time at which HCP responded to the request in Greenwich Mean Time (GMT). The date and time are returned in this format:

DDD dd MMM yyyy HH:mm:ss GMT

For example:

Thu, 14 Mat 2013 14:27:05 GMT
ETagString (Required)This value is the MD5 checksum of the uploaded object content. The value is not quoted. If you supplied an ETag request header and the operation was successful, the values are the same. If you did not supply an ETag request header, check the ETag response header value against the object content you have just uploaded.
Last-ModifiedString (Required)The date and time that the copied object was created or last had its metadata modified.
X-Copied-FromString

Shows the container and object name of the original source object from which the new object was copied.

This is the format:

 container/object
X-Copied-From-Last-ModifiedStringShows the last modified date and time for the original source object from which the new object was copied.
X-Object-Meta-nameStringFor object, specifies a custom metadata property/value pair. The response headers include one X-Object-Meta-name header for each applicable pair.
X-Trans-IdUuid (Required)HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database.
HTTP status codes

The table below describes HTTP status codes that can be returned in response to a request to copy an object.

CodeMeaningDescription
201SuccessNo response body.
404Not FoundThe specified source object does not exist.
408Request TimeoutThe request has timed out and the operation was not completed. HSwift is no longer retrying the operation.
409ConflictThe object exists already and versioning is not enabled.
410Gone

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.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

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 from one container to another and adding custom metadata

Here's a sample COPY request that copies an object named campaigns/GoGetEm.xls from the sales-mktg container to the finance container, where the target object that results from the copy operation is named mktg/campaign_GoGetEm_expenses.xls. With this copy, the metadata property/value pair business/campaign is added to the object.

Request with curl command line

curl -k -i -X COPY http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/sales-mktg/campaigns/GoGetEm.xls -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87" -H "Destination: finance/mktg/campaign_GoGetEm_expenses.xls" -H "X-Object-Meta-business: campaign"

Request headers

COPY /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/sales-mktg/campaign/GoGetEm.xls HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87
x-Object-business: campaign
Destination: /finance/mktg/campaign_GoGetEm_expenses.xls

Response headers

HTTP/1.1 201 Created
Date: Mon, 03 Nov 2014 14:06:29 GMT
X-Trans-Id: 1c66338b-d2e8-49ab-aa46-15f41677a919
ETag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: application/octet-stream
Content-Length: 0
X-Copied_From-Last-Modified:Mon, 03 Nov 2014 14:06:29 GMT
X-Copied-From: /finance/mktg/campaign_GoGetEm_expenses.xls
Last-Modified: Mon, 03 Nov 2014 14:06:29 GMT

Retrieving an object

You use the HTTP GET method to retrieve an object from a container. Retrieving an object means retrieving the object data. To retrieve an object, you need read permission for the container containing the object or for the object itself.

A request to retrieve an object retrieves the current version of the object. This happens regardless of whether or not versioning is enabled.

If a retrieved object has custom metadata, the headers returned in response to the request include the X-Object-Meta-name header which lists the name of each metadata item.

Request line

Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to retrieve an object has either of these formats:

  • With the Keystone tenant ID:
    GET /swift/v1/tenant-ID/container-name/directory-name/object-name HTTP/1.1
  • With the account name:
    Get /swift/v1/account-name/container-name/directory-name/object-name HTTP/1.1
Request headers

The table below describes the headers you can use in a request to retrieve an object.

NameTypeDescription
X-Auth-TokenString

Used to supply the Keystone authentication token or local authentication token.

Replace the Keystone authentication token with the prefix HCP, followed by your Local Authentication token, in the format:

"X-Auth-Token: HCP base64-encoded-username:md5-encoded-password"

For example:

"X-Auth-Token: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
If-MatchDict

Specifies one or more values for comparison with the ETag of the specified item. If the ETag matches one of the specified values, HCP continues processing the request. If the ETag doesn't match any of the specified values, HCP returns a 412 (Preconditions Failed) status code.

To specify the values for this header, use this format:

 "value"[, "value"]...

In this format, each value can be any string of one or more characters and must be enclosed in double quotation marks ("). Alternatively, you can specify a single asterisk (*) as the value for the If-Match header. All ETags match an asterisk in an If-Match header.

If-None-MatchString

Specifies one or more values for comparison with the ETag of the specified object. If the ETag matches any of the specified values, HCP returns a 304 (Not Modified) status code.

To specify the values for this header, use this format:

 "value"[, "value"]...

In this format, each value can be any string of one or more characters and must be enclosed in double quotation marks (").

Alternatively, you can specify a single asterisk (*) as the value for the If-None-Match header. No ETags match an asterisk in an If-None-Match header.

If-Modified-SinceDict

Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified object was last modified. If the modification date and time is later than the specified date and time, HCP continues processing the request. If the modification date and time is equal to or earlier than the specified date and time, HCP returns a 304 (Not Modified) status code.

To specify the date and time for this header, use one of these formats:

  • DDD, dd MMM yyyy HH:mm:ss(+0000|GMT)

    For example: Thu, 07 Mar 2013 14:27:05 +0000

  • DDDD, dd-MMM-yy HH:mm:ss(+0000|GMT)

    For example: Thursday, 07-Mar-13 14:27:05 +0000

  • DDD MMM d HH:mm:ss yyyy

    For example: Thu Mar 7 14:27:05 2013

In these formats:

  • DDD is the three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).
  • DDDD is the day of the week fully spelled out, with an uppercase first letter (for example, Monday).
  • d is the one- or two-digit day of the month, as applicable.
  • dd is the two-digit day of the month.
  • MMM is the three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).
  • yy is the last two digits of the year.
If-Unmodified-SinceDict

Specifies a date and time, in Greenwich Mean Time (GMT), for comparison with the date and time the specified object was last modified. If the modification date and time is equal to or earlier than the specified date and time, HCP continues processing the request. If the modification date and time is later than the specified date and time, HCP returns a 412 (Precondition Failed) status code.

For valid values for this header, see the description of the If-Modified-Since header above.

RangeDict

Retrieves part of an object.

To specify a byte range in a range header, you use this format:

"Range: bytes=byte-range,byte-range"

The list below shows the valid values for byte-range.

  • start-position–end-position

    Bytes in start-position through end-position, inclusive. If end-position is greater than the size of the object data, HCP returns the bytes in start-position through the end of the data.

    Valid values for start-position and end-position are integers greater than or equal to zero.

    For the specified range to be valid, end-position must be greater than or equal to start-position.

    For example: five hundred bytes beginning with the two-hundred-first:

    bytes=200-699
  • start-position–

    Bytes in start-position through the end of the object data.

    Valid values for start-position are integers greater than or equal to zero.

    For example: all the bytes beginning with the seventy-sixth and continuing through the end of the object data:

    bytes=75-
  • –offset-from-end

    Bytes in the offset-from-end position, counted back from the last position in the object data, through the end of the object data. If offset-from-end is greater than the size of the object data, HCP returns the complete object data.

    Valid values for offset-from-end are integers greater than or equal to zero.

    For example: the last 25 bytes of the object data:

    bytes=-25
Response headers

The table below describes the response headers returned in response to a successful request to retrieve an object.

NameTypeDescription
Accept-RangesString (Required)Always bytes. This header shows the type of ranges that an object accepts from a Range request header.
Content-EncodingStringSpecifies whether the request body is compressed. The only possible value for this response header is gzip.
Content-lengthString (Required)

The size, in bytes, of the response body if HCP can determine the size before formulating the response.

If the response does not include a response body, the value of the Content-Length is 0 (zero).

Content-TypeString (Required if the Content-Length is greater than 0)

The Internet media type of the response body if HCP can determine the Internet media type. If HCP cannot determine the Internet media type, the value of this header is application/octet-stream.

Because HCP returns error information in a response body, the response to any request can include a Content-Type header.

DateDatetime (Required)

The date and time at which HCP responded to the request in Greenwich Mean Time (GMT). The date and time are returned in this format:

DDD dd MMM yyyy HH:mm:ss GMT

For example:

Thu, 14 Mat 2013 14:27:05 GMT
ETagString (Required)This value is the MD5 checksum values of the object content.
Last-ModifiedString (Required)The date and time that the object was created or the last time that the metadata was modified.
X-Object-ManifestString

For multipart objects, specifies the name of the container in which the parts of the multipart object are stored, followed by the common prefix for the part names, in this format: container-name/prefix

This header is returned only for multipart objects.

X-Object-Meta-nameStringFor object, specifies a custom metadata property/value pair. The response headers include one X-Object-Meta-name header for each applicable pair.
X-Static-Large-ObjectStringAlways false. HCP does not support static large objects.
X-Trans-IdUuid (Required)HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database.
HTTP status codes

The table below describes HTTP status codes that can be returned in response to a request to retrieve an object.

CodeMeaningDescription
200Success

HCP successfully processed the request.

Note: If the number of bytes returned does not equal the value of the Content-Length response header, try the request again later.

304Not ModifiedIf using If-Non-Match header and Etag matches, or If-Modified-Since. The response body may contain information regarding the precondition failure.
403ForbiddenAuthenticated user does not have permission to perform the requested operation
404Not FoundThe object you requested could not be retrieved.
410Gone

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.
412Precondition FailedIf using If-Match header and Etag does not match, or if-Unmodified-Since. The response body may contain information regarding the precondition failure.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

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: Conditionally retrieving an object

Here's a sample GET request that retrieves an object named mktg/campaign_GoGetEm_expenses.xls in the finance container only if the ETag for the object doesn't match a specified value. In this example, the specified value is the ETag of mktg/campaign_GoGetEm_expenses.xls.

Request with curl command line

curl -k -X GET http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/mktg/campaign_GoGetEm_expenses.xls -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87" -H "If-None-Match: d41d8cd98f00b204e9800998ecf8427e"

Request headers

GET /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/mktg/campaign_GoGetEm_expenses.xls HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87
If-None-Match: d41d8cd98f00b204e9800998ecf8427e

Response headers

HTTP/1.1 304 Not Modified
Date: Fri, 24 Oct 2014 13:03:44 GMT
X-Trans-Id: 854ad794-2a9e-4d02-9012-35e43d3d69ec
Accept-Ranges: bytes
X-Static-Large-Object: false
ETag: "d41d8cd98f00b204e9800998ecf8427e"
Content-Type: text/html;charset=UTF-8
Content-Length: 0
Transfer-Encoding: chunked
Example: Retrieving part of an object

Here's a sample GET request that retrieves the first hundred thousand bytes of the object named quarterly_rpts/Q4_2012.ppt in the finance container.

Request with curl command line

curl -X -k GET http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/quarterly_rpts/Q4_2012.ppt -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87" -H "Range: bytes=0-99999"

Request headers

GET /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/quarterly_rpts/Q4_2012.ppt HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87
Range: bytes=0-99999

Response headers

HTTP/1.1 206 Partial Content
Date: Fri, 24 Oct 2014 14:03:39 GMT
Content-Length: 0
HTTP/1.1 200 OK

Date: Mon, 03 Nov 2014 14:54:48 GMT
X-Trans-Id: 9cb4f3af-2e8f-498c-9a9a-633b414c99a0
Accept-Ranges: bytes
X-Static-Large-Object: false
ETag: d41d8cd98f00b204e9800998ecf8427e
Last-Modified: Wed, 29 Oct 2014 13:40:34 GMT
Content-Length: 100000
Cache-Control: no-cache,no-store
Pragma: no-cache
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="directory";

Updating the metadata of an object

You use the HTTP POST method to create or update object metadata. To create or update object metadata, you need the write permission for the target container.

If you use the POST method on an object that already has custom metadata, the request overwrites the existing custom metadata. If you want to retain old metadata, you need to include it in the request.

Request line

Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to update the metadata of an object has either of these formats:

  • With the Keystone tenant ID:
    POST /swift/v1/tenant-ID/container-name/directory-name/object-name HTTP/1.1
  • With the account name:
    OST /swift/v1/account-name/container-name/directory-name/object-name HTTP/1.1
Request headers

The table below describes the headers you can use in a request to update the metadata of an object.

NameTypeDescription
X-Auth-TokenString

Used to supply the Keystone authentication token or local authentication token.

Replace the Keystone authentication token with the prefix HCP, followed by your Local Authentication token, in the format:

"X-Auth-Token: HCP base64-encoded-username:md5-encoded-password"

For example:

"X-Auth-Token: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
X-Object-Meta-nameStringFor objects only, specifies a custom metadata property/value pair. The response headers include one X-Object-Meta- header for each applicable pair.
Response headers

The table below describes the headers you can use in a request to update the metadata of an object.

NameTypeDescription
Content-lengthString (Required)

The size, in bytes, of the response body if HCP can determine the size before formulating the response.

If the response does not include a response body, the value of the Content-Length is 0 (zero).

Content-TypeString (Required if the Content-Length is greater than 0)

The Internet media type of the response body if HCP can determine the Internet media type. If HCP cannot determine the Internet media type, the value of this header is application/octet-stream.

Because HCP returns error information in a response body, the response to any request can include a Content-Type header.

DateDatetime (Required)

The date and time at which HCP responded to the request in Greenwich Mean Time (GMT). The date and time are returned in this format:

DDD dd MMM yyyy HH:mm:ss GMT

For example:

Thu, 14 Mat 2013 14:27:05 GMT
X-Trans-IdUuid (Required)HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database.
HTTP status codes

The table below describes HTTP status code that is returned in response to a request to create or update the metadata of an object.

CodeMeaningDescription
200SuccessThe object metadata has been updated.
Example: Updating the custom metadata of an object

Here's a sample POST request that updates the metadata of an object named sales_quotas_2013.pdf which has the existing custom metadata property/value pair business/campaign. The request updates the metadata property/value pair to business/finance.

Request with curl command line

curl -k -i -X POST http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/sales_quotas_2013.pdf -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87" -H "X-Object-Meta-business: finance"

Request headers

POST /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/sales_quotas_2013.pdf HTTP/1.1
X-Object-Meta-author: P.D Grey
X-Object-Meta-Book: Book 1
X-Object-Meta-Info: Info 1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87

Response headers

HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx4d9b4f1cd99e437fb9e79-0054206e7d
Date: Mon, 22 Sep 2013 18:46:21 GMT

Deleting an object or directory

You use the HTTP DELETE method to delete an object or directory in a container. To check the delete an object or container, you need write permission for the container containing the object or directory.

Request line

Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to delete an object has either of these formats:

  • With the Keystone tenant ID included in the hostname:
    DELETE /swift/v1/tenant-ID/container-name/directory-name/object-name HTTP/1.1
  • With the account name following the hostname:
    DELETE /swift/v1/account-name/container-name/directory-name/object-name HTTP/1.1

Depending on whether the HSwift request uses a Keystone tenant ID or the account name, the request line for a request to delete a directory has either of these formats:

  • With the Keystone tenant ID included in the hostname:
    DELETE /swift/v1/tenant-ID/container-name/directory-name/ HTTP/1.1
  • With the account name following the hostname:
    DELETE /swift/v1/account-name/container-name/directory-name/ HTTP/1.1
Request headers

The table below describes the headers you can use in a request to check the existence of an object or directory.

NameTypeDescription
X-Auth-TokenString

Used to supply the Keystone authentication token or local authentication token.

Replace the Keystone authentication token with the prefix HCP, followed by your Local Authentication token, in the format:

"X-Auth-Token: HCP base64-encoded-username:md5-encoded-password"

For example:

"X-Auth-Token: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
Response headers

The table below describes the response headers returned in response to a successful request to delete an object or directory.

NameTypeDescription
Content-lengthString (Required)

The size, in bytes, of the response body if HCP can determine the size before formulating the response.

If the response does not include a response body, the value of the Content-Length is 0 (zero).

Content-TypeString (Required if the Content-Length is greater than 0)

The Internet media type of the response body if HCP can determine the Internet media type. If HCP cannot determine the Internet media type, the value of this header is application/octet-stream.

Because HCP returns error information in a response body, the response to any request can include a Content-Type header.

DateDatetime (Required)

The date and time at which HCP responded to the request in Greenwich Mean Time (GMT). The date and time are returned in this format:

DDD dd MMM yyyy HH:mm:ss GMT

For example:

Thu, 14 Mat 2013 14:27:05 GMT
X-Trans-IdUuid (Required)HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database.
HTTP status codes

The table below describes HTTP status codes that can be returned in response to a request to delete an object or directory.

CodeMeaningDescription
204No ContentNo Response Body.
404Not FoundHTML error message in response body.
500Internal Server Error

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service Unavailable

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: Deleting an object

Here's a sample DELETE request that deletes an object named hum_res/budget_proposals/BudgProp-2013 from the finance container.

Request with curl command line

curl -v -X -k DELETE http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/hum_res/budget_proposals/BudgProp-2013 -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87"

Request headers

DELETE /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/hum_res/budget_proposals/BudgProp-2013 HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87

Response headers

HTTP/1.1 204 No Content
Date: Mon, 03 Nov 2014 15:04:57 GMT
Content-Type: text/html;charset=UTF-8
Content-Length: 538
Example: Deleting a directory

Here's a sample DELETE request that deletes a directory named hum_res/budget_proposals/ from the finance container.

Request with curl command line

curl -v -X -k DELETE http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/hum_res/budget_proposals/ -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87"

Request headers

DELETE /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/hum_res/budget_proposals/ HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87

Response headers

HTTP/1.1 204 No Content
Date: Mon, 03 Nov 2014 15:04:57 GMT

 

  • Was this article helpful?