< Previous | Contents | Next >

Listing bucket contents

You use the HTTP GET method to list the contents of a bucket. To list the contents of a bucket, you need browse permission for the bucket.

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

quarterly_rpts/ quarterly_rpts/Q4_2012

By default, a bucket listing includes only the current (or only) versions of objects. To request a listing that includes old versions of objects, you use the versions query parameter.

A listing that includes versions of objects may include deleted versions. A deleted version is a marker that indicates that the previous version of the object was deleted. For an introduction to object versions, see “Versioning” on page 34.

You can use query parameters to list only a subset of the items in a bucket. For information on using these parameters, see “Limiting the bucket listing” on page 98.

A bucket listing is returned in an XML response body. In the response body, items in the bucket listing occur in alphanumeric order. If the listing includes multiple versions of an object, those versions are listed in chronological order with the oldest version first.

The format of the bucket listing response body differs depending on whether the GET request includes the versions query parameter. For the formats of the bucket listing response body, see “Response body” on page 106.

Chapter 5: Working with buckets 97

Listing bucket contents

By default, a bucket listing can include at most one thousand items. However, you can use the max-keys 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.


Limiting the bucket listingLimiting a listing of current itemsdelimitermarkermax-keysprefixLimiting a version listingRequest lineRequest headersResponse headersResponse bodyResponse body for a listing of current itemsResponse body for a version listingResponse body elementsHTTP status codesExamplesExample 1: Listing the items in a folderExample 2: Listing items a few at a timeRequest for the first three itemsRequest for next three itemsExample 3: Listing the versions of an individual object