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