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