============================== 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 | | +-------------------+----------+---------------+