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.
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
The table below describes the headers you can use in a request to store an object.
Name | Type | Description |
X-Auth-Token | String |
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-Encoding | String | Specifies whether the request body is compressed. If so, enter gzip . |
Content-Length | Integer | Specifies the size, in bytes, of the data being stored. |
Etag | String |
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. |
Expect | String | Use 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-Match | String |
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 |
Transfer-Encoding | String | If 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-From | String |
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-Object-Meta-name | String | For objects only, specifies a custom metadata property/value pair. The response headers include one X-Object-Meta- header for each applicable pair. |
The table below describes the response headers returned in response to a successful request to store an object.
Name | Type | Description |
Content-length | String (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-Type | String (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 Because HCP returns error information in a response body, the response to any request can include a |
ETag | String (Required) | Contains the MD5 hash of the received file. |
Date | Datetime (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-Id | Uuid (Required) | HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database. |
The table below describes HTTP status codes that can be returned in response to a request to store an object.
Code | Meaning | Description |
201 | Created | The object has been added to the container. |
408 | Request Timeout | The request has timed out and not completed. It is no longer trying to resend the request. |
409 | Conflict | The object exists already and versioning is not enabled. |
411 | Length Required | Indicates a missing Transfer-Encoding or Content-Length request header. |
412 | Precondition Failed | If using "If-None-Match: *" header and an object already exists at the specified path. |
422 | Unprocessable Entity | MD5 checksum of the data that is written to the object store does not match the optional ETag value. |
500 | Internal Server Error |
An internal error occurred. If this error persists, contact your tenant administrator. |
503 | Service 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. |
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.
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
The table below describes the headers you can use in a request to create a directory.
Name | Type | Description |
X-Auth-Token | String |
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-Encoding | String | Specifies whether the request body is compressed. If so, enter gzip . |
Content-Length | Integer | Specifies the size, in bytes, of the data being stored. |
Etag | String |
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. |
Expect | String | Use 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-Match | String |
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 |
Transfer-Encoding | String | If 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-From | String |
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 |
The table below describes the response headers returned in response to a successful request to create a directory.
Name | Type | Description |
Content-length | String (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-Type | String (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 Because HCP returns error information in a response body, the response to any request can include a |
ETag | String (Required) | Specifies the ETag for the object. |
Date | Datetime (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-Id | Uuid (Required) | HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database. |
The table below describes HTTP status codes that can be returned in response to a request to store an object.
Code | Meaning | Description |
201 | Created | The object has been added to the container. |
408 | Request Timeout | The request has timed out and not completed. It is no longer trying to resent the request. |
409 | Conflict | The object already exists and versioning is not enabled. |
411 | Length Required | Indicates a missing Transfer-Encoding or Content-Length request header. |
412 | Precondition Failed | If using If-None-Match: * header and an object already exists at the specified path. |
422 | Unprocessable Entity | MD5 checksum of the data that is written to the object store does not match the optional ETag value. |
500 | Internal Server Error |
An internal error occurred. If this error persists, contact your tenant administrator. |
503 | Service 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. |
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.
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
The table below describes the headers you can use in a request to check the metadata of an object or directory.
Name | Type | Description |
X-Auth-Token | String |
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" |
The table below describes the headers you can use in a request to check the metadata of an object or directory.
Name | Type | Description |
Content-length | String (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-Type | String (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 Because HCP returns error information in a response body, the response to any request can include a |
Date | Datetime (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 |
ETag | String (Required) | This value is the MD5 checksum value of the object content. |
Last-Modified | String (Required) | The date and time that the object was created or the last time that the metadata was modified. |
X-Object-Manifest | String |
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-name | String (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-Object | String | Always false . HCP does not support static large objects. |
X-Trans-Id | Uuid (Required) | HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database. |
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.
Code | Meaning | Description |
200 | Success | The object data has been retrieved. |
204 | Request Timeout | The request has timed out and the operation was not completed. Hswift is no longer retrying the operation. |
500 | Internal Server Error |
An internal error occurred. If this error persists, contact your tenant administrator. |
503 | Service 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. |
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
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.
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.
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"
The table below describes the headers you can use in a request to copy an object.
Name | Type | Description |
X-Auth-Token | String |
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" |
Destination | String (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-name | String | For objects only, specifies a custom metadata property/value pair. The response headers include one X-Object-Meta- header for each applicable pair. |
The table below describes the response headers returned in response to a successful request to copy an object.
Name | Type | Description |
Content-length | String (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-Type | String (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 Because HCP returns error information in a response body, the response to any request can include a |
Date | Datetime (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 |
ETag | String (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-Modified | String (Required) | The date and time that the copied object was created or last had its metadata modified. |
X-Copied-From | String |
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-Modified | String | Shows the last modified date and time for the original source object from which the new object was copied. |
X-Object-Meta-name | String | For object, specifies a custom metadata property/value pair. The response headers include one X-Object-Meta-name header for each applicable pair. |
X-Trans-Id | Uuid (Required) | HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database. |
The table below describes HTTP status codes that can be returned in response to a request to copy an object.
Code | Meaning | Description |
201 | Success | No response body. |
404 | Not Found | The specified source object does not exist. |
408 | Request Timeout | The request has timed out and the operation was not completed. HSwift is no longer retrying the operation. |
409 | Conflict | The object exists already and versioning is not enabled. |
410 | Gone |
Possible reasons include:
|
500 | Internal Server Error |
An internal error occurred. If this error persists, contact your tenant administrator. |
503 | Service 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. |
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.
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
The table below describes the headers you can use in a request to retrieve an object.
Name | Type | Description |
X-Auth-Token | String |
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-Match | Dict |
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-None-Match | String |
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-Modified-Since | Dict |
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:
In these formats:
|
If-Unmodified-Since | Dict |
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 |
Range | Dict |
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.
|
The table below describes the response headers returned in response to a successful request to retrieve an object.
Name | Type | Description |
Accept-Ranges | String (Required) | Always bytes . This header shows the type of ranges that an object accepts from a Range request header. |
Content-Encoding | String | Specifies whether the request body is compressed. The only possible value for this response header is gzip . |
Content-length | String (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-Type | String (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 Because HCP returns error information in a response body, the response to any request can include a |
Date | Datetime (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 |
ETag | String (Required) | This value is the MD5 checksum values of the object content. |
Last-Modified | String (Required) | The date and time that the object was created or the last time that the metadata was modified. |
X-Object-Manifest | String |
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-name | String | 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-Object | String | Always false . HCP does not support static large objects. |
X-Trans-Id | Uuid (Required) | HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database. |
The table below describes HTTP status codes that can be returned in response to a request to retrieve an object.
Code | Meaning | Description |
200 | Success |
HCP successfully processed the request. Note: If the number of bytes returned does not equal the value of the |
304 | Not Modified | If using If-Non-Match header and Etag matches, or If-Modified-Since . The response body may contain information regarding the precondition failure. |
403 | Forbidden | Authenticated user does not have permission to perform the requested operation |
404 | Not Found | The object you requested could not be retrieved. |
410 | Gone |
Possible reasons include:
|
412 | Precondition Failed | If using If-Match header and Etag does not match, or if-Unmodified-Since . The response body may contain information regarding the precondition failure. |
500 | Internal Server Error |
An internal error occurred. If this error persists, contact your tenant administrator. |
503 | Service 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. |
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
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.
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
The table below describes the headers you can use in a request to update the metadata of an object.
Name | Type | Description |
X-Auth-Token | String |
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-name | String | For objects only, specifies a custom metadata property/value pair. The response headers include one X-Object-Meta- header for each applicable pair. |
The table below describes the headers you can use in a request to update the metadata of an object.
Name | Type | Description |
Content-length | String (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-Type | String (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 Because HCP returns error information in a response body, the response to any request can include a |
Date | Datetime (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-Id | Uuid (Required) | HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database. |
The table below describes HTTP status code that is returned in response to a request to create or update the metadata of an object.
Code | Meaning | Description |
200 | Success | The object metadata has been updated. |
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.
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
The table below describes the headers you can use in a request to check the existence of an object or directory.
Name | Type | Description |
X-Auth-Token | String |
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" |
The table below describes the response headers returned in response to a successful request to delete an object or directory.
Name | Type | Description |
Content-length | String (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-Type | String (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 Because HCP returns error information in a response body, the response to any request can include a |
Date | Datetime (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-Id | Uuid (Required) | HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database. |
The table below describes HTTP status codes that can be returned in response to a request to delete an object or directory.
Code | Meaning | Description |
204 | No Content | No Response Body. |
404 | Not Found | HTML error message in response body. |
500 | Internal Server Error |
An internal error occurred. If this error persists, contact your tenant administrator. |
503 | Service 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. |
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
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