ceph/doc/api/swift.rst

==============================
 Swift Compatible RESTful API
==============================

Protocols Interoperability
==========================

TBD

Authentication
==============

Using the Swift API, authenticated requests need to contain an
authentication token. The authentication token may be obtained through
an authenticator. The RGW can also serve as the authenticator. The 
``{api version}/{account}`` prefix that this documentation specify in each
request is also obtained through the authentication process.

Access Control Lists
====================

TBD

Common Swift Entities
=====================

Response Status
---------------

+---------------+-----------------------------------+-------------------+
| HTTP Status   | Response Code                     | Description       |
+===============+===================================+===================+
| 100           |                                   | Continue          |
+---------------+-----------------------------------+-------------------+
| 200           |                                   | Success           |
+---------------+-----------------------------------+-------------------+
| 201           | Created                           |                   |
+---------------+-----------------------------------+-------------------+
| 202           | Accepted                          |                   |
+---------------+-----------------------------------+-------------------+
| 204           | NoContent                         |                   |
+---------------+-----------------------------------+-------------------+
| 206           |                                   | Partial content   |
+---------------+-----------------------------------+-------------------+
| 304           | NotModified                       |                   |
+---------------+-----------------------------------+-------------------+
| 400           | InvalidArgument                   |                   |
+---------------+-----------------------------------+-------------------+
| 400           | InvalidDigest                     |                   |
+---------------+-----------------------------------+-------------------+
| 400           | BadDigest                         |                   |
+---------------+-----------------------------------+-------------------+
| 400           | InvalidBucketName                 |                   |
+---------------+-----------------------------------+-------------------+
| 400           | InvalidObjectName                 |                   |
+---------------+-----------------------------------+-------------------+
| 400           | UnresolvableGrantByEmailAddress   |                   |
+---------------+-----------------------------------+-------------------+
| 400           | RequestTimeout                    |                   |
+---------------+-----------------------------------+-------------------+
| 400           | EntityTooLarge                    |                   |
+---------------+-----------------------------------+-------------------+
| 401           | UserSuspended                     |                   |
+---------------+-----------------------------------+-------------------+
| 401           | AccessDenied                      |                   |
+---------------+-----------------------------------+-------------------+
| 403           | RequestTimeTooSkewed              |                   |
+---------------+-----------------------------------+-------------------+
| 404           | NoSuchKey                         |                   |
+---------------+-----------------------------------+-------------------+
| 404           | NoSuchBucket                      |                   |
+---------------+-----------------------------------+-------------------+
| 404           | NoSuchUpload                      |                   |
+---------------+-----------------------------------+-------------------+
| 405           | MethodNotAllowed                  |                   |
+---------------+-----------------------------------+-------------------+
| 408           | RequestTimeout                    |                   |
+---------------+-----------------------------------+-------------------+
| 409           | BucketAlreadyExists               |                   |
+---------------+-----------------------------------+-------------------+
| 409           | BucketNotEmpty                    |                   |
+---------------+-----------------------------------+-------------------+
| 411           | MissingContentLength              |                   |
+---------------+-----------------------------------+-------------------+
| 412           | PreconditionFailed                |                   |
+---------------+-----------------------------------+-------------------+
| 412           | Invalid UTF8                      |                   |
+---------------+-----------------------------------+-------------------+
| 412           | BadURL                            |                   |
+---------------+-----------------------------------+-------------------+
| 416           | InvalidRange                      |                   |
+---------------+-----------------------------------+-------------------+
| 422           | UnprocessableEntity               |                   |
+---------------+-----------------------------------+-------------------+
| 500           | InternalError                     |                   |
+---------------+-----------------------------------+-------------------+

Service Operations
==================

List Containers
---------------

A request that lists the buckets can only be run using a specific user's
credentials, and cannot be run anonymously

Syntax
~~~~~~

::

    GET /{api version}/{account} HTTP/1.1

Parameters
~~~~~~~~~~

+----------+-----------------+----------------+------------+
| Name     | Description     | Valid Values   | Required   |
+==========+=================+================+============+
| format   | result format   | json, xml      | No         |
+----------+-----------------+----------------+------------+
| marker   |                 |                | No         |
+----------+-----------------+----------------+------------+
| limit    |                 |                | No         |
+----------+-----------------+----------------+------------+

Headers
~~~~~~~

Response Entities
~~~~~~~~~~~~~~~~~

+-------------+-------------+---------------------------------------+
| Name        | Type        | Description                           |
+=============+=============+=======================================+
| account     | Container   | Container for list of containers      |
+-------------+-------------+---------------------------------------+
| container   | Container   | Container for container information   |
+-------------+-------------+---------------------------------------+
| name        | String      | Bucket name                           |
+-------------+-------------+---------------------------------------+
| bytes       | Integer     | Total container size                  |
+-------------+-------------+---------------------------------------+

Container Operations
====================

Create Container
----------------

Creates a new container.

Syntax
~~~~~~

::

    PUT /{api version}/{account}/{container} HTTP/1.1

Parameters
~~~~~~~~~~

Headers
~~~~~~~

+-----------------------+---------------+------------+
| Name                  | Description   | Required   |
+=======================+===============+============+
| X-Container-Read      |               | No         |
+-----------------------+---------------+------------+
| X-Container-Write     |               | No         |
+-----------------------+---------------+------------+
| X-Container-Meta-\*   |               | No         |
+-----------------------+---------------+------------+

HTTP Response
~~~~~~~~~~~~~

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.

+---------------+-----------------------+-------------------------------------------------------------+
| HTTP Status   | Status Code           | Description                                                 |
+===============+=======================+=============================================================+
| 409           | BucketAlreadyExists   | Container already exists under different user's ownership   |
+---------------+-----------------------+-------------------------------------------------------------+

Remove Container
----------------

Deletes a container. Container name can be reused following a successful
container removal.

Syntax
~~~~~~

::

    DELETE /{api version}/{account}/{container} HTTP/1.1

Headers
~~~~~~~

HTTP Response
~~~~~~~~~~~~~

+---------------+---------------+---------------------+
| HTTP Status   | Status Code   | Description         |
+===============+===============+=====================+
| 204           | NoContent     | Container removed   |
+---------------+---------------+---------------------+

15.3List Container Objects
--------------------------

Syntax
~~~~~~

::

    GET /{api version}/{container} HTTP/1.1

Parameters
~~~~~~~~~~

+-------------+-----------------+----------------+------------+
| Name        | Description     | Valid Values   | Required   |
+=============+=================+================+============+
| format      | result format   | json, xml      | No         |
+-------------+-----------------+----------------+------------+
| prefix      |                 |                | No         |
+-------------+-----------------+----------------+------------+
| marker      |                 |                | No         |
+-------------+-----------------+----------------+------------+
| limit       |                 |                | No         |
+-------------+-----------------+----------------+------------+
| delimiter   |                 |                | No         |
+-------------+-----------------+----------------+------------+
| path        |                 |                | No         |
+-------------+-----------------+----------------+------------+

Response Entities
~~~~~~~~~~~~~~~~~

+------------------+-------------+---------------+
| Name             | Type        | Description   |
+==================+=============+===============+
| container        | Container   |               |
+------------------+-------------+---------------+
| object           | Container   |               |
+------------------+-------------+---------------+
| name             | String      |               |
+------------------+-------------+---------------+
| hash             | String      |               |
+------------------+-------------+---------------+
| last\_modified   | Date        |               |
+------------------+-------------+---------------+
| hash             | String      |               |
+------------------+-------------+---------------+
| content\_type    | String      |               |
+------------------+-------------+---------------+

Update Container Metadata
-------------------------

Syntax
~~~~~~

::

    POST /{api version}/{account}/{container} HTTP/1.1

Request Headers
~~~~~~~~~~~~~~~

+---------------------+---------------+----------------+------------+
| Name                | Description   | Valid Values   | Required   |
+=====================+===============+================+============+
| X-Container-Read    |               |                | No         |
+---------------------+---------------+----------------+------------+
| X-Container-Write   |               |                | No         |
+---------------------+---------------+----------------+------------+

Object Operations
=================

Put Object
----------

Syntax
~~~~~~

::

    PUT /{api version}/{account}/{container}/{object} HTTP/1.1

Request Headers
~~~~~~~~~~~~~~~

+---------------------+---------------+----------------+------------+
| Name                | Description   | Valid Values   | Required   |
+=====================+===============+================+============+
| ETag                |               |                | No         |
+---------------------+---------------+----------------+------------+
| Content-Type        |               |                | No         |
+---------------------+---------------+----------------+------------+
| Transfer-Encoding   |               | chunked        | No         |
+---------------------+---------------+----------------+------------+

Copy Object
-----------

Syntax
~~~~~~

::

    PUT /{api version}/{account}/{dest-container}/{dest-object} HTTP/1.1
    x-amz-copy-source: {source-container}/{source-object}

or alternatively:

::

    COPY /{api version}/{account}/{source-container}/{source-object} HTTP/1.1
    Destination: {dest-container}/{dest-object}

Request Headers
~~~~~~~~~~~~~~~

+-----------------------+---------------+----------------+--------------+
| Name                  | Description   | Valid Values   | Required     |
+=======================+===============+================+==============+
| X-Copy-From           |               |                | Yes (PUT)    |
+-----------------------+---------------+----------------+--------------+
| Destination           |               |                | Yes (COPY)   |
+-----------------------+---------------+----------------+--------------+
| If-Modified-Since     |               |                | No           |
+-----------------------+---------------+----------------+--------------+
| If-Unmodified-Since   |               |                | No           |
+-----------------------+---------------+----------------+--------------+
| Copy-If-Match         |               |                | No           |
+-----------------------+---------------+----------------+--------------+
| Copy-If-None-Match    |               |                | No           |
+-----------------------+---------------+----------------+--------------+

Remove Object
-------------

Removes an object. Requires WRITE permission set on the containing
container.

Syntax
~~~~~~

::

    DELETE /{api version}/{account}/{container}/{object} HTTP/1.1

Get Object
----------

Syntax
~~~~~~

::

    GET /{api version}/{account}/{container}/{object} HTTP/1.1

Request Headers
~~~~~~~~~~~~~~~

+-----------------------+---------------+----------------+------------+
| Name                  | Description   | Valid Values   | Required   |
+=======================+===============+================+============+
| Range                 |               |                | No         |
+-----------------------+---------------+----------------+------------+
| If-Modified-Since     |               |                | No         |
+-----------------------+---------------+----------------+------------+
| If-Unmodified-Since   |               |                | No         |
+-----------------------+---------------+----------------+------------+
| If-Match              |               |                | No         |
+-----------------------+---------------+----------------+------------+
| If-None-Match         |               |                | No         |
+-----------------------+---------------+----------------+------------+

Response Headers
~~~~~~~~~~~~~~~~

+-----------------+--------------------------------------------------------------------------------------------+
| Name            | Description                                                                                |
+=================+============================================================================================+
| Content-Range   | Data range, will only be returned if the range header field was specified in the request   |
+-----------------+--------------------------------------------------------------------------------------------+

Get Object Info
---------------

Returns information about object. This request will return the same
header information as with the Get Object request, but will not include
the object data payload.

Syntax
~~~~~~

::

    HEAD /{api version}/{account}/{container}/{object} HTTP/1.1

Request Headers
~~~~~~~~~~~~~~~

+-----------------------+---------------+----------------+------------+
| Name                  | Description   | Valid Values   | Required   |
+=======================+===============+================+============+
| Range                 |               |                | No         |
+-----------------------+---------------+----------------+------------+
| If-Modified-Since     |               |                | No         |
+-----------------------+---------------+----------------+------------+
| If-Unmodified-Since   |               |                | No         |
+-----------------------+---------------+----------------+------------+
| If-Match              |               |                | No         |
+-----------------------+---------------+----------------+------------+
| If-None-Match         |               |                | No         |
+-----------------------+---------------+----------------+------------+

Update Object Metadata
----------------------

Syntax
~~~~~~

::

    POST /{api version}/{account}/{container}/{object} HTTP/1.1

Request Headers
~~~~~~~~~~~~~~~

+--------------------+----------+---------------+
| Name               | Type     | Description   |
+====================+==========+===============+
| X-Object-Meta-\*   | String   |               |
+--------------------+----------+---------------+

Swift Auth Compatible RESTful API
=================================

The Swift Auth API is being used for the generation of tokens that can
be used with the RGW Swift API.

Auth Get
--------

Syntax
~~~~~~

::

    GET /auth HTTP/1.1

Request Headers
~~~~~~~~~~~~~~~

+---------------+----------+---------------+
| Name          | Type     | Description   |
+===============+==========+===============+
| X-Auth-Key    | String   |               |
+---------------+----------+---------------+
| X-Auth-User   | String   |               |
+---------------+----------+---------------+

Response Headers
~~~~~~~~~~~~~~~~

+-------------------+----------+---------------+
| Name              | Type     | Description   |
+===================+==========+===============+
| X-Storage-Url     | String   |               |
+-------------------+----------+---------------+
| X-Storage-Token   | String   |               |
+-------------------+----------+---------------+