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";