Storage Container Services

This section documents the ReST operations that can be performed on containers. All operations are valid HTTP request methods and will resemble this format:

Example 3.11. Storage Container HTTP Request: General Structure

  METHOD /v1/<account>/<container> HTTP/1.1

GET operations against a storage container name are performed to retrieve a list of objects stored in the container. Additionally, there are a number of optional query parameters that can be used to refine the list results.

A request with no query parameters will return the full list of object names stored in the container, up to 10,000 names. Optionally specifying the query parameters will filter the full list and return a subset of objects.

Query Parameters

limit

For an integer value n , limits the number of results to at most n values.

marker

Given a string value x , return object names greater in value than the specified marker.

prefix

For a string value x , causes the results to be limited to object names beginning with the substring x .

format

Specify either json or xml to return the respective serialized response.

path

For a string value x , return the object names nested in the pseudo path (assuming preconditions are met - see below).

delimiter

For a character c , return all the object names nested in the container (without the need for the directory marker objects).

Example 3.12. Objects List Request

  GET /<api version>/<account>/<container>[?parm=value] HTTP/1.1
  Host: storage.swiftdrive.com
  X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

A list of objects is returned in the response body, one object name per line. A 204 (No Content) HTTP return code will be passed back if the container is empty or does not exist for the specified account. If an incorrect account is specified, the HTTP return code will be 404 (Not Found).

Example 3.13. Objects List Response

  HTTP/1.1 200 Ok
  Date: Thu, 07 Jun 2010 18:50:19 GMT
  Server: Apache
  Content-Type: text/plain; charset=UTF-8
  Content-Length: 171
                    
  kate_beckinsale.jpg
  How To Win Friends And Influence People.pdf
  moms_birthday.jpg
  poodle_strut.mov
  Disturbed - Down With The Sickness.mp3
  army_of_darkness.avi
  the_mad.avi

If a format=xml or format=json argument is appended to the storage account URL, the service will serve extended object information serialized in the chosen format. Other than the ?format=xml|json param, it will return the same status/errors codes. The sample responses below are formatted for readability.

Example 3.14. Objects Details Request: JSON 

  GET /<api version>/<account>/<container>?format=json HTTP/1.1
  Host: storage.swiftdrive.com
  Content-Length: 0
  X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4

Example 3.15. Objects Details Response: JSON 

  HTTP/1.1 200 OK
  Date: Tue, 25 Nov 2008 19:39:13 GMT
  Server: Apache
  Content-Length: 387
  Content-Type: application/json; charset=utf-8
                    
 [
   {"name":"test_obj_1",
    "hash":"4281c348eaf83e70ddce0e07221c3d28",
    "bytes":14,
    "content_type":"application\/octet-stream",
    "last_modified":"2009-02-03T05:26:32.612278"},
   {"name":"test_obj_2",
    "hash":"b039efe731ad111bc1b0ef221c3849d0",
    "bytes":64,
    "content_type":"application\/octet-stream",
    "last_modified":"2009-02-03T05:26:32.612278"},
 ]

Example 3.16. Objects Details Request: XML

  GET /<api version>/<account>/<container>?format=xml HTTP/1.1
  Host: storage.swiftdrive.com
  X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4

Example 3.17. Objects Details Request: XML 

  HTTP/1.1 200 OK
  Date: Tue, 25 Nov 2008 19:42:35 GMT
  Server: Apache
  Content-Length: 643
  Content-Type: application/xml; charset=utf-8
                    
  <?xml version="1.0" encoding="UTF-8"?>

  <container name="test_container_1">
    <object>
      <name>test_object_1</name>
      <hash>4281c348eaf83e70ddce0e07221c3d28</hash>
      <bytes>14</bytes>
      <content_type>application/octet-stream</content_type>
      <last_modified>2009-02-03T05:26:32.612278</last_modified>
    </object>
    <object>
      <name>test_object_2</name>
      <hash>b039efe731ad111bc1b0ef221c3849d0</hash>
      <bytes>64</bytes>
      <content_type>application/octet-stream</content_type>
      <last_modified>2009-02-03T05:26:32.612278</last_modified>
    </object>
  </container>

The system will return a maximum of 10,000 object names per request. To retrieve subsequent object names, another request must be made with a 'marker' parameter. The marker indicates where the last list left off and the system will return object names greater than this marker, up to 10,000 again. Note that the ‘marker’ value should be URL encoded prior to sending the HTTP request.

If 10,000 is larger than desired, a 'limit' parameter may be given.

If the number of object names returned equals the limit given (or 10,000 if no limit is given), it can be assumed there are more object names to be listed. If the container name list is exactly divisible by the limit, the last request will simply have no content.

Example 3.18. List Large Number of Objects

For an example, let's use a listing of five object names:

  gala
  grannysmith
  honeycrisp
  jonagold
  reddelicious

We'll use a limit of two to show how things work:

  GET /<api version>/<account>/<container>?limit=2
  Host: storage.swiftdrive.com
  X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
                    
  gala
  grannysmith

Since we received two items back, we can assume there are more object names to list. So, we make another request with a marker of the last item returned:

  GET /<api version>/<account>/<container>?limit=2&marker=grannysmith
  Host: storage.swiftdrive.com
  X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
                    
  honeycrisp
  jonagold

Again we have two items returned; there may be more:

  GET /<api version>/<account>/<container>?limit=2&marker=oranges
  Host: storage.swiftdrive.com
  X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
                    
  reddelicious

Now we received less than the limit number of container names, indicating that we have the complete list.


You can simulate a hierarchical structure in OpenStack Object Storage by following a few guidelines. Object names must contain the forward slash character / as a path element separator and also create directory marker objects; then they will be able to traverse this nested structure with the new path query parameter. This can best be illustrated by example:

Note

For the purposes of this example, the container where the objects reside is called backups. All objects in this example start with a prefix of photos and should NOT be confused with the container name. In the example, the full URI of the me.jpg file would be https://storage.swiftdrive.com/v1/CF_xer7_343/backups/photos/me.jpg

Example 3.19. Pseudo-Hierarchical Folders/Directories

In the example, the following real objects are uploaded to the storage system with names representing their full filesystem path:

  photos/animals/dogs/poodle.jpg
  photos/animals/dogs/terrier.jpg
  photos/animals/cats/persian.jpg
  photos/animals/cats/siamese.jpg
  photos/plants/fern.jpg
  photos/plants/rose.jpg
  photos/me.jpg

To take advantage of this feature, the directory marker objects must also be created to represent the appropriate directories. The following additional objects need to be created. A good convention would be to create these as zero- or one-byte files with a Content-Type of application/directory.

  photos/animals/dogs
  photos/animals/cats
  photos/animals
  photos/plants
  photos

Now issuing a GET request against the container name coupled with the path query parameter of the directory to list can traverse these directories. Only the request line and results are depicted below excluding other request/response headers.

  GET /v1/AccountString/backups?path=photos HTTP/1.1
  Host: storage.swiftdrive.com
  X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
                    
  photos/animals
  photos/cats
  photos/me.jpg

To traverse down into the animals directory, specify that path.

  GET /v1/AccountString/backups?path=photos/animals
  Host: storage.swiftdrive.com
  X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
                    
  photos/animals/dogs
  photos/animals/cats

By combining this path query parameter with the format query parameter, users will be able to easily distinguish between virtual folders/directories by Content-Type and build interfaces that allow traversal of the pseudo-nested structure.

You can also use a delimiter parameter to represent a nested directory hierarchy without the need for the directory marker objects. You can use any single character as a delimiter. The listings can return virtual directories - they are virtual in that they don't actually represent real objects. like the directory markers, though, they will have a content-type of application/directory and be in a subdir section of json and xml results.

If you have the following objects—photos/photo1, photos/photo2, movieobject, videos/movieobj4—in a container, your delimiter parameter query using slash (/) would give you photos, movieobject, videos.

GET /v1/acct/container?delimiter=/
Host: storage.swiftdrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

PUT operations against a storage container are used to create that container.

Containers are storage compartments for your data. The URL encoded name must be less than 256 bytes and cannot contain a forward slash '/' character.

Example 3.20. Container Create Request 

  PUT /<api version>/<account>/<container> HTTP/1.1
  Host: storage.swiftdrive.com
  X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

No content is returned. A status code of 201 (Created) indicates that the container was created as requested. Container PUT requests are idempotent and a code of 202 (Accepted) is returned when the container already existed.

Example 3.21. Container Create Response

  HTTP/1.1 201 Created
  Date: Thu, 07 Jun 2010 18:50:19 GMT
  Server: Apache
  Content-Type: text/plain; charset=UTF-8

DELETE operations against a storage container are used to permanently remove that container. The container must be empty before it can be deleted.

A HEAD request against the container can be used to determine if it contains any objects.

Example 3.22. Container Delete Request

  DELETE /<api version>/<account>/<container> HTTP/1.1
  Host: storage.swiftdrive.com
  X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

'Response '

No content is returned. A status code of 204 (No Content) indicates success, 404 (Not Found) is returned if the requested container was not found, and a 409 (Conflict) if the container is not empty. No response body will be generated.

Example 3.23. Container Delete Response

  HTTP/1.1 204 No Content
  Date: Thu, 07 Jun 2010 18:57:07 GMT
  Server: Apache
  Content-Length: 0
  Content-Type: text/plain; charset=UTF-8

HEAD operations against a storage container are used to determine the number of objects, and the total bytes of all objects stored in the container. Since the storage system is designed to store large amounts of data, care should be taken when representing the total bytes response as an integer; when possible, convert it to a 64-bit unsigned integer if your platform supports that primitive type.

Example 3.24. Container Metadata Request

  HEAD /<api version>/<account>/<container> HTTP/1.1
  Host: storage.swiftdrive.com
  X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

The HTTP return code will be 204 (No Content) if the container exists, and 404 (Not Found) if it does not. The object count and utilization are returned in the X-Container-Object-Count and X-Container-Bytes-Used headers respectively.

Example 3.25. Container Metadata Response

  HTTP/1.1 204 No Content
  Date: Wed, 11 Jul 2010 19:37:41 GMT
  Content-type: text/html
  X-Container-Object-Count: 7
  X-Container-Bytes-Used: 413

Prev Up Next
 Home