ceph/doc/radosgw/s3/bucketops.rst

===================
 Bucket Operations
===================

PUT Bucket
----------
Creates a new bucket. To create a bucket, you must have a user ID and a valid AWS Access Key ID to authenticate requests. You may not
create buckets as an anonymous user.

.. note:: We do not support request entities for ``PUT /{bucket}`` in this release.

Constraints
~~~~~~~~~~~
In general, bucket names should follow domain name constraints.

- Bucket names must be unique.
- Bucket names must begin and end with a lowercase letter.
- Bucket names may contain a dash (-).

Syntax
~~~~~~

::

    PUT /{bucket} HTTP/1.1
    Host: cname.domain.com
    x-amz-acl: public-read-write

    Authorization: AWS {access-key}:{hash-of-header-and-secret}

Parameters
~~~~~~~~~~

+---------------+----------------------+-----------------------------------------------------------------------------+------------+
| Name          | Description          | Valid Values                                                                | Required   |
+===============+======================+=============================================================================+============+
| ``x-amz-acl`` | Canned ACLs.         | ``private``, ``public-read``, ``public-read-write``, ``authenticated-read`` | No         |
+---------------+----------------------+-----------------------------------------------------------------------------+------------+



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

If the bucket name is unique, within constraints and unused, the operation will succeed.
If a bucket with the same name already exists and the user is the bucket owner, the operation will succeed.
If the bucket name is already in use, the operation will fail.

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

DELETE Bucket
-------------

Deletes a bucket. You can reuse bucket names following a successful bucket removal.

Syntax
~~~~~~

::

    DELETE /{bucket} HTTP/1.1
    Host: cname.domain.com

    Authorization: AWS {access-key}:{hash-of-header-and-secret}

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

+---------------+---------------+------------------+
| HTTP Status   | Status Code   | Description      |
+===============+===============+==================+
| ``204``       | No Content    | Bucket removed.  |
+---------------+---------------+------------------+

GET Bucket
----------
Returns a list of bucket objects.

Syntax
~~~~~~

::

    GET /{bucket}?max-keys=25 HTTP/1.1
    Host: cname.domain.com

Parameters
~~~~~~~~~~

+-----------------+-----------+-----------------------------------------------------------------------+
| Name            | Type      | Description                                                           |
+=================+===========+=======================================================================+
| ``prefix``      | String    | Only returns objects that contain the specified prefix.               |
+-----------------+-----------+-----------------------------------------------------------------------+
| ``delimiter``   | String    | The delimiter between the prefix and the rest of the object name.     |
+-----------------+-----------+-----------------------------------------------------------------------+
| ``marker``      | String    | A beginning index for the list of objects returned.                   |
+-----------------+-----------+-----------------------------------------------------------------------+
| ``max-keys``    | Integer   | The maximum number of keys to return. Default is 1000.                |
+-----------------+-----------+-----------------------------------------------------------------------+


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

+---------------+---------------+--------------------+
| HTTP Status   | Status Code   | Description        |
+===============+===============+====================+
| ``200``       | OK            | Buckets retrieved  |
+---------------+---------------+--------------------+

Bucket Response Entities
~~~~~~~~~~~~~~~~~~~~~~~~
``GET /{bucket}`` returns a container for buckets with the following fields.

+------------------------+-----------+----------------------------------------------------------------------------------+
| Name                   | Type      | Description                                                                      |
+========================+===========+==================================================================================+
| ``ListBucketResult``   | Entity    | The container for the list of objects.                                           |
+------------------------+-----------+----------------------------------------------------------------------------------+
| ``Name``               | String    | The name of the bucket whose contents will be returned.                          |
+------------------------+-----------+----------------------------------------------------------------------------------+
| ``Prefix``             | String    | A prefix for the object keys.                                                    |
+------------------------+-----------+----------------------------------------------------------------------------------+
| ``Marker``             | String    | A beginning index for the list of objects returned.                              |
+------------------------+-----------+----------------------------------------------------------------------------------+
| ``MaxKeys``            | Integer   | The maximum number of keys returned.                                             |
+------------------------+-----------+----------------------------------------------------------------------------------+
| ``Delimiter``          | String    | If set, objects with the same prefix will appear in the ``CommonPrefixes`` list. |
+------------------------+-----------+----------------------------------------------------------------------------------+
| ``IsTruncated``        | Boolean   | If ``true``, only a subset of the bucket's contents were returned.               |
+------------------------+-----------+----------------------------------------------------------------------------------+
| ``CommonPrefixes``     | Container | If multiple objects contain the same prefix, they will appear in this list.      |
+------------------------+-----------+----------------------------------------------------------------------------------+

Object Response Entities
~~~~~~~~~~~~~~~~~~~~~~~~
The ``ListBucketResult`` contains objects, where each object is within a ``Contents`` container.

+------------------------+-----------+------------------------------------------+
| Name                   | Type      | Description                              |
+========================+===========+==========================================+
| ``Contents``           | Object    | A container for the object.              |
+------------------------+-----------+------------------------------------------+
| ``Key``                | String    | The object's key.                        |
+------------------------+-----------+------------------------------------------+
| ``LastModified``       | Date      | The object's last-modified date/time.    |
+------------------------+-----------+------------------------------------------+
| ``ETag``               | String    | An MD-5 hash of the object. (entity tag) |
+------------------------+-----------+------------------------------------------+
| ``Size``               | Integer   | The object's size.                       |
+------------------------+-----------+------------------------------------------+
| ``StorageClass``       | String    | Should always return ``STANDARD``.       |
+------------------------+-----------+------------------------------------------+


Get Bucket ACL
--------------
Retrieves the bucket access control list. The user needs to be the bucket
owner or to have been granted ``READ_ACP`` permission on the bucket.

Syntax
~~~~~~
Add the ``acl`` subresource to the bucket request as shown below.

::

    GET /{bucket}?acl HTTP/1.1
    Host: cname.domain.com

    Authorization: AWS {access-key}:{hash-of-header-and-secret}

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

+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| Name                      | Type        | Description                                                                                  |
+===========================+=============+==============================================================================================+
| ``AccessControlPolicy``   | Container   | A container for the response.                                                                |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| ``AccessControlList``     | Container   | A container for the ACL information.                                                         |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| ``Owner``                 | Container   | A container for the bucket owner's ``ID`` and ``DisplayName``.                               |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| ``ID``                    | String      | The bucket owner's ID.                                                                       |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| ``DisplayName``           | String      | The bucket owner's display name.                                                             |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| ``Grant``                 | Container   | A container for ``Grantee`` and ``Permission``.                                              |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| ``Grantee``               | Container   | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission.  |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| ``Permission``            | String      | The permission given to the ``Grantee`` bucket.                                              |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+

PUT Bucket ACL
--------------
Sets an access control to an existing bucket. The user needs to be the bucket
owner or to have been granted ``WRITE_ACP`` permission on the bucket.

Syntax
~~~~~~
Add the ``acl`` subresource to the bucket request as shown below.

::

    PUT /{bucket}?acl HTTP/1.1

Request Entities
~~~~~~~~~~~~~~~~

+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| Name                      | Type        | Description                                                                                  |
+===========================+=============+==============================================================================================+
| ``AccessControlPolicy``   | Container   | A container for the request.                                                                 |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| ``AccessControlList``     | Container   | A container for the ACL information.                                                         |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| ``Owner``                 | Container   | A container for the bucket owner's ``ID`` and ``DisplayName``.                               |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| ``ID``                    | String      | The bucket owner's ID.                                                                       |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| ``DisplayName``           | String      | The bucket owner's display name.                                                             |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| ``Grant``                 | Container   | A container for ``Grantee`` and ``Permission``.                                              |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| ``Grantee``               | Container   | A container for the ``DisplayName`` and ``ID`` of the user receiving a grant of permission.  |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+
| ``Permission``            | String      | The permission given to the ``Grantee`` bucket.                                              |
+---------------------------+-------------+----------------------------------------------------------------------------------------------+

List Bucket Multipart Uploads
-----------------------------

``GET /?uploads`` returns a list of the current in-progress multipart uploads--i.e., the application initiates a multipart upload, but
the service hasn't completed all the uploads yet.

Syntax
~~~~~~

::

    GET /{bucket}?uploads HTTP/1.1

Parameters
~~~~~~~~~~

You may specify parameters for ``GET /{bucket}?uploads``, but none of them are required.

+------------------------+-----------+--------------------------------------------------------------------------------------+
| Name                   | Type      | Description                                                                          |
+========================+===========+======================================================================================+
| ``prefix``             | String    | Returns in-progress uploads whose keys contains the specified prefix.                |
+------------------------+-----------+--------------------------------------------------------------------------------------+
| ``delimiter``          | String    | The delimiter between the prefix and the rest of the object name.                    |
+------------------------+-----------+--------------------------------------------------------------------------------------+
| ``key-marker``         | String    | The beginning marker for the list of uploads.                                        |
+------------------------+-----------+--------------------------------------------------------------------------------------+
| ``max-keys``           | Integer   | The maximum number of in-progress uploads. The default is 1000.                      |
+------------------------+-----------+--------------------------------------------------------------------------------------+
| ``max-uploads``        | Integer   | The maximum number of multipart uploads. The range from 1-1000. The default is 1000. |
+------------------------+-----------+--------------------------------------------------------------------------------------+
| ``upload-id-marker``   | String    | Ignored if ``key-marker`` isn't specified. Specifies the ``ID`` of first             |
|                        |           | upload to list in lexicographical order at or following the ``ID``.                  |
+------------------------+-----------+--------------------------------------------------------------------------------------+


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

+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| Name                                    | Type        | Description                                                                                              |
+=========================================+=============+==========================================================================================================+
| ``ListMultipartUploadsResult``          | Container   | A container for the results.                                                                             |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``ListMultipartUploadsResult.Prefix``   | String      | The prefix specified by the ``prefix`` request parameter (if any).                                       |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``Bucket``                              | String      | The bucket that will receive the bucket contents.                                                        |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``KeyMarker``                           | String      | The key marker specified by the ``key-marker`` request parameter (if any).                               |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``UploadIdMarker``                      | String      | The marker specified by the ``upload-id-marker`` request parameter (if any).                             |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``NextKeyMarker``                       | String      | The key marker to use in a subsequent request if ``IsTruncated`` is ``true``.                            |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``NextUploadIdMarker``                  | String      | The upload ID marker to use in a subsequent request if ``IsTruncated`` is ``true``.                      |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``MaxUploads``                          | Integer     | The max uploads specified by the ``max-uploads`` request parameter.                                      |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``Delimiter``                           | String      | If set, objects with the same prefix will appear in the ``CommonPrefixes`` list.                         |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``IsTruncated``                         | Boolean     | If ``true``, only a subset of the bucket's upload contents were returned.                                |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``Upload``                              | Container   | A container for ``Key``, ``UploadId``, ``InitiatorOwner``, ``StorageClass``, and ``Initiated`` elements. |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``Key``                                 | String      | The key of the object once the multipart upload is complete.                                             |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``UploadId``                            | String      | The ``ID`` that identifies the multipart upload.                                                         |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``Initiator``                           | Container   | Contains the ``ID`` and ``DisplayName`` of the user who initiated the upload.                            |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``DisplayName``                         | String      | The initiator's display name.                                                                            |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``ID``                                  | String      | The initiator's ID.                                                                                      |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``Owner``                               | Container   | A container for the ``ID`` and ``DisplayName`` of the user who owns the uploaded object.                 |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``StorageClass``                        | String      | The method used to store the resulting object. ``STANDARD`` or ``REDUCED_REDUNDANCY``                    |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``Initiated``                           | Date        | The date and time the user initiated the upload.                                                         |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``CommonPrefixes``                      | Container   | If multiple objects contain the same prefix, they will appear in this list.                              |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+
| ``CommonPrefixes.Prefix``               | String      | The substring of the key after the prefix as defined by the ``prefix`` request parameter.                |
+-----------------------------------------+-------------+----------------------------------------------------------------------------------------------------------+