Chapter 3. Object Gateway Swift Application Programming Interface (API)

To authenticate a user, make a request containing an X-Auth-User and a X-Auth-Key in the header.

GET /auth HTTP/1.1
Host: swift.radosgwhost.com
X-Auth-User: johndoe
X-Auth-Key: R7UUOLFDI2ZI9PRCQ53K

The response from the server should include an X-Auth-Token value. The response might also contain a X-Storage-Url that provides the <api_version>/<account> prefix that is specified in other requests throughout the API documentation.

HTTP/1.1 204 No Content
Date: Mon, 16 Jul 2012 11:05:33 GMT
Server: swift
X-Storage-Url: https://swift.radosgwhost.com/v1/ACCT-12345
X-Storage-Token: UOlCCC8TahFKlWuv9DB09TWHF0nDjpPElha0kAa
Content-Length: 0
Content-Type: text/plain; charset=UTF-8

A GET request that specifies the API version and the account will return a list of containers for a particular user account. Since the request returns a particular user’s containers, the request requires an authentication token. The request cannot be made anonymously.

GET /<api_version>/<account> HTTP/1.1
Host: <Fully_Qualified_Domain_Name>
X-Auth-Token: <auth_token>

The response contains a list of containers, or returns with an HTTP 204 response code

Return to the features table.

When a client application accesses containers, it always operates with credentials of a particular user. In Red Hat Ceph Storage 3, every user belongs to a tenant. See Multi Tenancy for additional details. Consequently, every container operation has an implicit tenant in its context if no tenant is specified explicitly. Thus multi tenancy is completely backward compatible with previous releases, as long as the referred containers and referring user belong to the same tenant.

Extensions employed to specify an explicit tenant differ according to the protocol and authentication system used.

A colon character separates tenant and container, thus a sample URL would be:

https://rgw.domain.com/tenant:container

By contrast, in a create_container() method, simply separate the tenant and container in the container method itself:

create_container("tenant:container")

To create a new container, make a PUT request with the API version, account, and the name of the new container. The container name must be unique, must not contain a forward-slash (/) character, and should be less than 256 bytes. You can include access control headers and metadata headers in the request. You can also include a storage policy identifying a key for a set of placement pools, for example, execute radosgw-admin zone get to see a list of available keys under placement_pools. A storage policy enables you to specify a special set of pools for the container, for example, SSD-based storage. The operation is idempotent; that is, if you make a request to create a container that already exists, it will return with a HTTP 202 return code, but will not create another container.

PUT /<api_version>/<account>/<tenant>:<container> HTTP/1.1
Host: <Fully_Qualified_Domain_Name>
X-Auth-Token: <auth_token>
X-Container-Read: <comma_separated_uids>
X-Container-Write: <comma_separated_uids>
X-Container-Meta-<key>: <value>
X-Storage-Policy: <placement_pools_key>

If a container with the same name already exists, and the user is the container owner then the operation will succeed. Otherwise the operation will fail.

Return to the features table.

To list the objects within a container, make a GET request with the with the API version, account, and the name of the container. You can specify query parameters to filter the full list, or leave out the parameters to return a list of the first 10,000 object names stored in the container.

GET /<api_version>/<tenant>:<container> HTTP/1.1
 Host: <Fully_Qualified_Domain_Name>
 X-Auth-Token: <auth_token>

Return to the features table.

When a user creates a container, the user has read and write access to the container by default. To allow other users to read a container’s contents or write to a container, you must specifically enable the user. You can also specify * in the X-Container-Read or X-Container-Write settings, which effectively enables all users to either read from or write to the container. Setting * makes the container public. That is it enables anonymous users to either read from or write to the container.

POST /<api_version>/<account>/<tenant>:<container> HTTP/1.1
Host: <Fully_Qualified_Domain_Name>
 X-Auth-Token: <auth_token>
 X-Container-Read: *
 X-Container-Write: <uid1>, <uid2>, <uid3>

Return to the features table.

To add metadata to a container, make a POST request with the API version, account, and container name. You must have write permissions on the container to add or update metadata.

POST /<api_version>/<account>/<tenant>:<container> HTTP/1.1
Host: <Fully_Qualified_Domain_Name>
 X-Auth-Token: <auth_token>
 X-Container-Meta-Color: red
 X-Container-Meta-Taste: salty

Return to the features table.

To delete a container, make a DELETE request with the API version, account, and the name of the container. The container must be empty. If you’d like to check if the container is empty, execute a HEAD request against the container. Once you’ve successfully removed the container, you’ll be able to reuse the container name.

DELETE /<api version>/<account>/<tenant>:<container> HTTP/1.1
Host: <Fully_Qualified_Domain_Name>
X-Auth-Token: <auth-token>

Return to the features table.

To create a new object, make a PUT request with the API version, account, container name and the name of the new object. You must have write permission on the container to create or update an object. The object name must be unique within the container. The PUT request is not idempotent, so if you do not use a unique name, the request will update the object. However, you can use pseudo-hierarchical syntax in the object name to distinguish it from another object of the same name if it is under a different pseudo-hierarchical directory. You can include access control headers and metadata headers in the request.

PUT /<api_version>/<account>/<tenant>:<container>/<object> HTTP/1.1
 Host: <Fully_Qualified_Domain_Name>
 X-Auth-Token: <auth_token>

Return to the features table.

Copying an object allows you to make a server-side copy of an object, so that you don’t have to download it and upload it under another container/name. To copy the contents of one object to another object, you can make either a PUT request or a COPY request with the API version, account, and the container name. For a PUT request, use the destination container and object name in the request, and the source container and object in the request header. For a Copy request, use the source container and object in the request, and the destination container and object in the request header. You must have write permission on the container to copy an object. The destination object name must be unique within the container. The request is not idempotent, so if you do not use a unique name, the request will update the destination object. However, you can use pseudo-hierarchical syntax in the object name to distinguish the destination object from the source object of the same name if it is under a different pseudo-hierarchical directory. You can include access control headers and metadata headers in the request.

PUT /<api_version>/<account>/<tenant>:<dest_container>/<dest_object> HTTP/1.1
X-Copy-From: <tenant>:<source_container>/<source_object>
Host: <Fully_Qualified_Domain_Name>
X-Auth-Token: <auth_token>

or alternatively:

COPY /<api_version>/<account>/<tenant>:<source_container>/<source_object> HTTP/1.1
Destination: <tenant>:<dest_container>/<dest_object>

Return to the features table.

To delete an object, make a DELETE request with the API version, account, container and object name. You must have write permissions on the container to delete an object within it. Once you’ve successfully deleted the object, you’ll be able to reuse the object name.

DELETE /<api_version>/<account>/<tenant>:<container>/<object> HTTP/1.1
Host: <Fully_Qualified_Domain_Name>
X-Auth-Token: <auth_token>

Return to the features table.

To retrieve an object, make a GET request with the API version, account, container and object name. You must have read permissions on the container to retrieve an object within it.

GET /<api version>/<account>/<tenant>:<container>/<object> HTTP/1.1
Host: <Fully_Qualified_Domain_Name>
X-Auth-Token: <auth-token>

Return to the features table.

To retrieve an object’s metadata, make a HEAD request with the API version, account, container and object name. You must have read permissions on the container to retrieve metadata from an object within the container. This request returns the same header information as the request for the object itself, but it does not return the object’s data.

HEAD /<api_version>/<account>/<tenant>:<container>/<object> HTTP/1.1
Host: <Fully_Qualified_Domain_Name>
X-Auth-Token: <auth_token>

Return to the features table.

To add metadata to an object, make a POST request with the API version, account, container and object name. You must have write permissions on the parent container to add or update metadata.

POST /<api_version>/<account>/<tenant>:<container>/<object> HTTP/1.1
Host: <Fully_Qualified_Domain_Name>
X-Auth-Token: <auth_token>

Return to the features table.

A POST request to the swift account with the required Key will set the secret temp url key for the account against which temporary url access can be provided to accounts. Up to two keys are supported, and signatures are checked against both the keys, if present, so that keys can be rotated without invalidating the temporary urls.

POST /<api_version>/<account> HTTP/1.1
Host: <Fully_Qualified_Domain_Name>
X-Auth-Token: <auth_token>

Temporary URL uses a cryptographic HMAC-SHA1 signature, which includes the following elements:

The above items are normalized with newlines appended between them, and a HMAC is generated using the SHA-1 hashing algorithm against one of the Temp URL Keys posted earlier.

A sample python script to demonstrate the above is given below:

import hmac
from hashlib import sha1
from time import time

method = 'GET'
host = 'https://objectstore.example.com'
duration_in_seconds = 300  # Duration for which the url is valid
expires = int(time() + duration_in_seconds)
path = '/v1/your-bucket/your-object'
key = 'secret'
hmac_body = '%s\n%s\n%s' % (method, expires, path)
hmac_body = hmac.new(key, hmac_body, sha1).hexdigest()
sig = hmac.new(key, hmac_body, sha1).hexdigest()
rest_uri = "{host}{path}?temp_url_sig={sig}&temp_url_expires={expires}".format(
     host=host, path=path, sig=sig, expires=expires)
print rest_uri

https://objectstore.example.com/v1/your-bucket/your-object?temp_url_sig=ff4657876227fc6025f04fcf1e82818266d022c6&temp_url_expires=1423200992