RepoMirrors/ceph
1
0
Fork 0
mirror of https://github.com/ceph/ceph synced 2024-12-26 05:25:09 +00:00
Code Issues Packages Projects Releases Wiki Activity
a1696fe0f3
ceph/doc/radosgw/swift.rst
John Wilkins 0be2611158 doc: Published RADOS GW docs and install as is for now. Needs more work. 
Signed-off-by: John Wilkins <john.wilkins@inktank.com>
2012-06-26 08:21:05 -07:00

485 lines
18 KiB
ReStructuredText
Raw Blame History

==============================
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 | |
+-------------------+----------+---------------+
Reference in New Issue View Git Blame Copy Permalink