Listing container contents

You use the HTTP GET method to list the contents of a container and its ACLs. To list the contents of a container, you need browse permission for the container.

For the purpose of a container listing, the container contents consist not only of the objects you stored in the container but also of the directories that you created in the container or that HCP created automatically from the object names. For example, by default, if a container contains an object named quarterly_rpts/Q4_2012, a list of the container contents includes these two items:

quarterly_rpts/
quarterly_rpts/Q4_2012

By default, a container listing includes only the current (or only) versions of objects. You cannot request to view older versions of objects using HSwift.

You can use query parameters to list only a subset of the items in a container.

A container listing is returned in a plain text response body although the format can be changed to either an XML or JSON response body. In the response body, items in the container listing occur in alphanumeric order.

By default, a container listing can include at most 10,000 items. However, you can use the limit query parameter in a request to specify a smaller maximum number of items. If more than the maximum number of items satisfy the criteria for a request, you can resubmit the request using query parameters to retrieve the next part of the listing.

You use query parameters to limit the items included in a object listing.

Request line

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

  • With the Keystone tenant ID:
    GET /swift/v1/tenant-ID/container-name[?query-parameters] HTTP/1.1
  • With the account name:
    GET /swift/v1/account-name/container-name[?query-parameters] HTTP/1.1

In these formats, query-parameters can be none, one, or a combination of the query parameters described below.

  • delimiter

    The delimiter parameter is a single alphanumeric character used to request all objects in a container up through the first occurrence of the character specified by the parameter.

    The delimiter parameter may be used to request directory listings where the forward (/) slash character is the path delimiter. Using the forward slash delimiter in combination with the prefix parameter, you can list the contents of any directory in the container. Omit the path parameter to list the root directory.

    When you use the delimiter query parameter, the listing includes both objects and directories. If you omit the delimiter query parameter, GET requests only list objects.

    For example, this is the content of an container:

    Items:

    AcctgBestPractices.doc
    acctg/
    hum_res/
    mktg/
    mktg/campaign_GoGetEm_expenses.xls
    mktg/campaign_LiveIt_expenses.xls
    quarterly_rpts/
    quarterly_rpts/budget_proposals/Q2_2012.ppt
    quarterly_rpts/budget_proposals/Q3_2012.ppt
    quarterly_rpts/budget_proposals/quotas/Q4_2012.ppt
    sales/
    sales_quotas_2013.pdf

    The container listing returned in response to a GET request with the delimiter=/ query parameter contains these items:

    Returned values:

    AcctgBestPractices.doc
    acctg/
    hum_res/
    mktg/
    quarterly_rpts/
    sales/
    sales_quotas_2013.pdf

    The lists of named items included in a listing are subject to any other character specified in the request.

    NoteThis query parameter can only be used to request a container listing, not an account listing.

  • format

    You use the format query parameter to determine the way the response body is formatted. The default method is plain text, but this can be changed to either XML or JSON.

    The Accept request header serves the same function as the format query parameter. If they are both used, the Accept header is ignored.

    Here is an example of how to use the query parameter:

    format=xml

  • limit

    You use the limit query parameter to limit the number of items in the returned container listing to fewer than 10,000.

    For example, the container listing returned in response to a GET request with the limit=5 query parameter contains these items:

    AcctgBestPractices.doc
    mktg/campaign_GoGetEm_expenses.xls
    mktg/campaign_LiveIt_expenses.xls
    quarterly_rpts/budget_proposals/Q2_2012.ppt
    quarterly_rpts/budget_proposals/Q3_2012.ppt

  • marker

    A container listing is returned in alphabetical order. You use the marker query parameter to only list the items that sort alphabetically after the value of the marker parameter.

    This is useful for paging through long lists of objects in a container. Using the name of the last object in the current page as the marker parameter retrieves the next page of objects.

    For example, the container listing returned in response to a GET request with the marker=mktg/campaign_LiveIt_expenses.xls query parameter contains these items because they all appear after mktg/campaign_LiveIt_expenses.xls:

    quarterly_rpts/budget_proposals/Q2_2012.ppt
    quarterly_rpts/budget_proposals/Q3_2012.ppt
    quarterly_rpts/budget_proposals/quotas/Q4_2012.ppt
    sales/budget_proposals/BudgProp-2013
    sales_quotas_2013.pdf

    If the string you specify as the value of the marker query parameter is the name of a directory and does not end with a forward slash (/), items that begin with that string followed by a forward slash are omitted from the listing.

  • end_marker

    You use the end_marker query parameter to only list the items that sort alphabetically before the value of the end_marker parameter.

    For example, the container listing returned in response to a GET request with the end_marker=quarterly_rpts/ query parameter contains these items:

    AcctgBestPractices.doc
    mktg/campaign_GoGetEm_expenses.xls
    mktg/campaign_LiveIt_expenses.xls

  • path

    You use the path query parameter to list all objects within the directory of a specified path. If there are subdirectories in the selected path the contents of the subdirectories are not listed. For instance, the following objects are returned in response to GET container request:

    AcctgBestPractices.doc
    acctg/
    hum_res/
    mktg/
    mktg/campaign_GoGetEm_expenses.xls
    mktg/campaign_LiveIt_expenses.xls
    quarterly_rpts/
    quarterly_rpts/budget_proposals/Q2_2012.ppt
    quarterly_rpts/budget_proposals/Q3_2012.ppt
    quarterly_rpts/budget_proposals/quotas/Q4_2012.ppt
    sales/
    sales_quotas_2013.pdf

    path=quarterly_rpts returns:

    quarterly_rpts/
    quarterly_rpts/budget_proposals/

  • prefix

    You use the prefix query parameter to request a container listing that contains only items with names that begin with the specified character string (the prefix).

    The prefix query parameter is used in conjunction with the delimiter parameter to list the contents of directories.

    For example, the container listing returned in response to a GET request with the prefix=sales query parameter contains only these items:

    sales/budget_proposals/BudgProp-2013
    sales_quotas_2013.pdf

Request headers

The table below describes the headers you can use in a request to list the contents of a container.

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

Set this header to application/json, application/xml, or text/xml. The response body will be serialized in the specified format.

This can also be accomplished with the format query parameter. If you use both at once, the response body defers to the format provided by the query parameter.

Response headers

The table below describes the response headers returned in response to a successful request to list the contents of a container.

NameTypeDescription
Accept-RangesString (Required)Always bytes. This header shows the type of ranges that an object accepts from a Range request header.
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-Container-Bytes-UsedInt (Required)The total amount of bytes of data stored in the container. This number is capped by the X-Container-Meta-Quota-Bytes header.
X-Container-Meta-Quota-BytesStringIf a quota has been set on the amount of bytes that can be stored by this container, this header returns the size, in bytes, of objects that can be stored in the container.
X-Container-Object-CountInt (Required)The total number of objects stored in the container. This number includes all objects in all directories that are in the container. Directories are not included in this number.
X-Trans-IdUuid (Required)HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database.

Response body

The response body returned in response to a request to list the contents of a container in an XML response body, in this format:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<container name="sales-practice">
     <object>
          <name>mktg/campaign_GoGetEm_expenses.xls</name>
          <hash>D357101A82D4F262E25860284C13EAC58F9A27A6AD70491BC6AAB4FB5113ABBC</hash>
          <bytes>23040</bytes>
          <content_type>application/octet-stream</content_type>
          <last_modified>2014-10-31T12:39:16.000055</last_modified>
          <subdir xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
     </object>
</container>

The list below describes the XML elements in this response body. The elements are listed in alphabetical order.

  • Bytes

    Child of the Object element.

    The Bytes element specifies the size, in bytes, of the content of the item.

    The response body includes Bytes elements for the listed folders. However, because folders have no content, the value of this element for a folder is always 0 (zero).

  • Container

    Root element.

  • Content-Type

    Child of the Object element.

    The Content-Type element specifies 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.

  • Hash

    Child of the Object element.

    The Hash element specified the calculated the Base64-encoded MD5 hash of the item.

  • Last_Modified

    Child of the Object element.

    The Last_Modified element specifies the date and time at which the target object was last modified, in Greenwich Mean Time (GMT). The date and time are expressed in this format:

    yyyy-MM-ddTHH:mm:ss.SSSZ

    For example:

    2014-10-20T16:34:27.000135

    Modifying an object means modifying its metadata. You cannot modify the content of an object.

  • Object

    Child of the Container element and container for the Bytes, Content-Type, Hash, Last Modified and subdir xsi:nil elements.

    The response body contains one Container element for each container you own.

  • subdir xsi:nil="true | false"

    Child of the Container element.

    The response body specifies whether the Object element is a sub-directory (true) or object (false).

    The response body lists elements for sub-directories as well as objects. However, because sub-directories have no content, the value of the Bytes element is always 0 (zero) and the value of the Content_Type is always application/octet-stream.

HTTP status codes

The table below describes HTTP status codes that can be returned in response to a request to list container contents.

CodeMeaningDescription
200OKThe response body lists the objects.
204No ContentThe response body shows no objects. Either the container has no objects or you are paging through a long list of names by using the marker, limit, or end_marker query parameters, and you have reached the end of the list.
404Not FoundIf the container does not exist.
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: Listing the items in a directory

Here's a sample GET request for a container listing that lists the objects that are in the mktg directory and, separately, the subdirectories that are in the mktg directory. The requests uses these query parameters:

  • prefix=mktg/

    lists only items that start with mktg/

  • marker=mktg/

    Starts the listing with the item that follows mktg/ by itself

  • delimiter=/

    Treats items that have a forward slash (/) after mktg/ as having a common prefix

Request with curl command line

curl -i -X GET http://api.hcp.example.com/swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance?prefix=mktg&marker=l&delimiter=/" -H "X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87" -H "Accept: application/xml"

Request headers

GET /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance?prefix=mktg&marker=mktg&delimiter=/" HTTP/1.1
X-Auth-Token: dc5efec8f546455eac974e7bbfd0dd87

Response headers

HTTP/1.1 200 OK
Date: Fri, 31 Oct 2014 16:41:58 GMT
X-Trans-Id: 2a6d516f-b78b-418b-aea3-12fc86316ad4
X-Container-Object-Count: 2
X-Container-Bytes-Used: 46080
X-Container-Meta-Quota-Bytes: 53687091200
X-Container-Read:
X-Container-Write:
Content-Type: application/xml;charset=UTF-8