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 aftermktg/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.
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" |
Accept | String |
Set this header to 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.
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-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-Container-Bytes-Used | Int (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-Bytes | String | If 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-Count | Int (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-Id | Uuid (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 always0
(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 isapplication/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 theBytes
,Content-Type
,Hash
,Last Modified
andsubdir 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 always0
(zero) and the value of theContent_Type
is alwaysapplication/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.
Code | Meaning | Description |
200 | OK | The response body lists the objects. |
204 | No Content | The 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. |
404 | Not Found | If the container does not exist. |
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. |
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 itselfdelimiter=/
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