.. _GET Service ostor-buckets:

GET Service ostor-buckets
-------------------------

Description
~~~~~~~~~~~

Lists information on all buckets or the buckets of the user specified by either email or ID.

Requests
~~~~~~~~

Syntax
^^^^^^

::

    GET /?ostor-buckets HTTP/1.1
    Host: s3.amazonaws.com
    Date: <date>
    Authorization: <authorization_string>

::

    GET /?ostor-buckets&emailAddress=<value> HTTP/1.1
    Host: s3.amazonaws.com
    Date: <date>
    Authorization: <authorization_string>

::

    GET /?ostor-buckets&id=<value> HTTP/1.1
    Host: s3.amazonaws.com
    Date: <date>
    Authorization: <authorization_string>

Parameters
^^^^^^^^^^

+------------------+-------------------------------------------------------+----------+
| Parameter        | Description                                           | Required |
+==================+=======================================================+==========+
| ``emailAddress`` | User email address.                                   | No*      |
|                  |                                                       |          |
|                  | Type: string.                                         |          |
|                  |                                                       |          |
|                  | Default value: none.                                  |          |
+------------------+-------------------------------------------------------+----------+
| ``id``           | User ID.                                              | No*      |
|                  |                                                       |          |
|                  | Type: string.                                         |          |
|                  |                                                       |          |
|                  | Default value: none.                                  |          |
+------------------+-------------------------------------------------------+----------+

\* Only one of the required parameters can be set in a single request.

If neither ``emailAddress`` nor ``id`` are set, the response is the list of all buckets, otherwise the response is the bucket list of the user with the specified email or ID.

Headers
^^^^^^^

This implementation uses only common request headers.

Responses
~~~~~~~~~

Headers
^^^^^^^

This implementation uses only common response headers.

Body
^^^^

A JSON dictionary with a bucket list in the following format:

::

    {
    "Buckets": [
    {
         "name": <name>,
         "epoch": <epoch>,
         "creation_date": <date>,
         "owner_id": <id>,
         "size": 
         {
              "current" : <cur>,
              "hmax": <hmax>,
              "h_integral": <hint>,
              "last_ts": <last_ts>
         }
    },
    {
    ...
    }]
    }
 
Errors
^^^^^^

Returns ``Error Code 400`` if more than one parameter is set.

Examples
~~~~~~~~

Sample Request
^^^^^^^^^^^^^^

Returns information on all buckets in S3.

::

    GET /?ostor-buckets HTTP/1.1
    Host: s3.amazonaws.com
    Date: Wed, 30 Apr 2016 22:32:00 GMT 
    Authorization: <authorization_string>

Sample Response
^^^^^^^^^^^^^^^

::

   {
   "Buckets": [
       {
           "size": {
               "current": 12288,
               "h_integral": 7360512,
               "hmax": 12288,
               "last_ts": 424241
           },
           "epoch": 0,
           "owner_id": "ba7eba06129464c5",
           "name": "bucket1",
           "creation_date": "2018-05-25T17:12:00.000Z"
       },
       {
           "size": {
               "current": 46700160,
               "h_integral": 28160196480,
               "hmax": 46700160,
               "last_ts": 424237
           },
           "epoch": 0,
           "owner_id": "ccbec013d9fd3918",
           "name": "bucket2",
           "creation_date": "2018-05-25T13:51:55.000Z"
       },
       {
           "size": {
               "current": 12288,
               "h_integral": 8036352,
               "hmax": 12288,
               "last_ts": 424186
           },
           "epoch": 0,
           "owner_id": "9d80d59edbe2862a",
           "name": "bucket3",
           "creation_date": "2018-05-23T10:30:49.000Z"
       }
   ]}