openstack
/
swift
Code Issues Proposed changes

Corrections for the API specifications in api-ref 

Fixes a number of technical issues with the api-ref section
including:

- Added missing headers
- The header descriptions were made specific to whether they
  are used in requests or responses and the verb in question
  (example: Content-Length in object HEAD is the object size,
  not the response body length).
- Added references to API features such as bulk delete.
- Many typographical fixes (e.g., spaces in the middle
  of header names)
- Restored xml and json account/container listing
  examples.

The following areas were not updated and it is proposed
to defer them to a subsequent update. This is because
I don't have time or their merit is debatable:

- ACLs (as used in a Keystone context) are not
  described.
- Account create/delete is not described.
- I left List Endpoints as-is.

Change-Id: I315b4e550b7d10880fbc00fce9311127ba609c2d
This commit is contained in:
Donagh McCabe 2016-08-12 15:52:55 +01:00
parent 2f659884f7
commit 9ce596a5a6
8 changed files with 585 additions and 402 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
api-ref/source/index.rst
View File

@ -6,8 +6,10 @@
.. rest_expand_all::
.. include:: storage-account-services.inc
.. include:: storage_endpoints.inc
.. include:: storage-object-services.inc
.. include:: storage-container-services.inc
.. include:: storage_info.inc
.. include:: storage-account-services.inc
.. include:: storage-container-services.inc
.. include:: storage-object-services.inc
.. include:: storage_endpoints.inc

4
api-ref/source/metadata_header_encoding.inc Normal file
View File

@ -0,0 +1,4 @@
The metadata value must be UTF-8-encoded and then
URL-encoded before you include it in the header.
This is a direct violation of the HTTP/1.1 `basic rules
<http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2>`_.

483
api-ref/source/parameters.yaml
View File

@ -22,9 +22,9 @@ Content-Disposition:
in: header
required: false
type: string
Content-Disposition_1:
Content-Disposition_resp:
description: |
If set, specifies the override behavior for the
If present, specifies the override behavior for the
browser. For example, this header might specify that the browser
use a download program to save this file rather than show the
file, which is the default. If not set, this header is not
@ -39,37 +39,36 @@ Content-Encoding:
in: header
required: false
type: string
Content-Encoding_1:
Content-Encoding_resp:
description: |
If set, the value of the ``Content-Encoding``
If present, the value of the ``Content-Encoding``
metadata. If not set, the operation does not return this header.
in: header
required: false
type: string
Content-Length:
Content-Length_cud_resp:
description: |
If the operation succeeds, this value is zero
(0). If the operation fails, this value is the length of the error
(0) or the length of informational or error
text in the response body.
in: header
required: true
type: string
Content-Length_1:
Content-Length_get_resp:
description: |
Set to the length of the object content. Do not
set if chunked transfer encoding is being used.
in: header
required: false
type: integer
Content-Length_2:
description: |
The length of the response body that contains the
list of names. If the operation fails, this value is the length of
the error text in the response body.
The length of the object content in the response
body, in bytes.
in: header
required: true
type: string
Content-Length_3:
Content-Length_listing_resp:
description: |
If the operation succeeds, the length of the response body
in bytes. On error, this is the length of the error text.
in: header
required: true
type: string
Content-Length_obj_head_resp:
description: |
HEAD operations do not return content. The
``Content-Length`` header value is not the size of the response
@ -77,33 +76,22 @@ Content-Length_3:
in: header
required: true
type: string
Content-Length_4:
Content-Length_put_req:
description: |
The length of the object content in the response
body, in bytes.
Set to the length of the object content (i.e. the length in bytes
of the request body). Do not
set if chunked transfer encoding is being used.
in: header
required: true
type: string
Content-Type:
required: false
type: integer
Content-Type_cud_resp:
description: |
Changes the MIME type for the object.
If present, this value is the MIME
type of the informational or error text in the response body.
in: header
required: false
type: string
Content-Type_1:
description: |
If the operation fails, this value is the MIME
type of the error text in the response body.
in: header
required: true
type: string
Content-Type_2:
description: |
The MIME type of the object.
in: header
required: true
type: string
Content-Type_3:
Content-Type_listing_resp:
description: |
The MIME type of the list of names. If the
operation fails, this value is the MIME type of the error text in
@ -111,23 +99,25 @@ Content-Type_3:
in: header
required: true
type: string
Content-Type_obj_cu_req:
description: |
Sets the MIME type for the object.
in: header
required: false
type: string
Content-Type_obj_resp:
description: |
The MIME type of the object.
in: header
required: true
type: string
Date:
description: |
The transaction date and time.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC. In the previous example, the offset value is ``-05:00``.
A ``null`` value indicates that the token never expires.
The date and time the system responded to the request,
using the preferred format of
`RFC 7231 <https://tools.ietf.org/html/rfc7231#section-7.1.1.1>`_ as
shown in this example ``Thu, 16 Jun 2016 15:10:38 GMT``. The time is
always in UTC.
in: header
required: true
type: string
@ -140,14 +130,29 @@ Destination:
in: header
required: true
type: string
ETag:
Destination-Account:
description: |
Specifies the account name where the object is copied to. If not
specified, the object is copied to the account which owns the object
(i.e., the account in the path).
in: header
required: false
type: string
ETag_obj_copied:
description: |
The MD5 checksum of the copied object content.
The value is not quoted.
in: header
required: true
type: string
ETag_1:
ETag_obj_received:
description: |
The MD5 checksum of the uploaded object content.
The value is not quoted.
in: header
required: true
type: string
ETag_obj_req:
description: |
The MD5 checksum value of the request body. For
example, the MD5 checksum value of the object content. You are
@ -158,7 +163,7 @@ ETag_1:
in: header
required: false
type: string
ETag_2:
ETag_obj_resp:
description: |
For objects smaller than 5 GB, this value is the
MD5 checksum of the object content. The value is not quoted. For
@ -190,7 +195,7 @@ If-Modified-Since:
If-None-Match:
description: |
In combination with ``Expect: 100-Continue``,
specify an ``"If- None-Match: *"`` header to query whether the
specify an ``"If-None-Match: *"`` header to query whether the
server already has a copy of the object before any data is sent.
in: header
required: false
@ -205,19 +210,10 @@ If-Unmodified-Since:
Last-Modified:
description: |
The date and time when the object was created or its metadata was
changed.
changed. The date and time is formaatted as shown in this
example: ``Fri, 12 Aug 2016 14:24:16 GMT``
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
For example, ``2015-08-27T09:49:58-05:00``.
The ``±hh:mm`` value, if included, is the time zone as an offset
from UTC. In the previous example, the offset value is ``-05:00``.
The time is always in UTC.
in: header
required: true
type: string
@ -233,18 +229,21 @@ Range:
do, the value defaults to the offset of the last byte of data.
- **Suffix byte range specification**. Use LENGTH bytes to specify
the length of the data range. The following forms of the header
specify the following ranges of data: - ``Range: bytes=-5``. The
last five bytes. - ``Range: bytes=10-15``. The six bytes of data
after a 10-byte offset. - ``Range: bytes=10-15,-5``. A multi-
part response that contains the last five bytes and the six
bytes of data after a 10-byte offset. The ``Content-Type``
response header contains ``multipart/byteranges``. - ``Range:
bytes=4-6``. Bytes 4 to 6 inclusive. - ``Range: bytes=2-2``. Byte
2, the third byte of the data. - ``Range: bytes=6-``. Byte 6 and
after. - ``Range: bytes=1-3,2-5``. A multi-part response that
contains bytes 1 to 3 inclusive, and bytes 2 to 5 inclusive. The
``Content-Type`` response header contains
``multipart/byteranges``.
specify the following ranges of data:
- ``Range: bytes=-5``. The last five bytes.
- ``Range: bytes=10-15``. The six bytes of data after a 10-byte offset.
- ``Range: bytes=10-15,-5``. A multi-part response that contains the
last five bytes and the six
bytes of data after a 10-byte offset. The ``Content-Type``
response header contains ``multipart/byteranges``.
- ``Range: bytes=4-6``. Bytes 4 to 6 inclusive.
- ``Range: bytes=2-2``. Byte 2, the third byte of the data.
- ``Range: bytes=6-``. Byte 6 and after.
- ``Range: bytes=1-3,2-5``. A multi-part response that
contains bytes 1 to 3 inclusive, and bytes 2 to 5 inclusive. The
``Content-Type`` response header contains
``multipart/byteranges``.
in: header
required: false
type: string
@ -272,23 +271,31 @@ X-Account-Container-Count:
X-Account-Meta-name:
description: |
The custom account metadata item, where
``{name}`` is the name of the metadata item. One ``X-Account-
Meta- {name}`` response header appears for each metadata item (for
each ``{name}``).
``name`` is the name of the metadata item. One ``X-Account-Meta-name``
response header appears for each metadata item (for
each ``name``).
in: header
required: false
type: string
X-Account-Meta-name_1:
X-Account-Meta-name_req:
description: |
The account metadata. The ``{name}`` is the name
The account metadata. The ``name`` is the name
of metadata item that you want to add, update, or delete. To
delete this item, send an empty value in this header. You must
specify an ``X-Account-Meta- {name}`` header for each metadata
item (for each ``{name}``) that you want to add, update, or
specify an ``X-Account-Meta-name`` header for each metadata
item (for each ``name``) that you want to add, update, or
delete.
in: header
required: false
type: string
X-Account-Meta-Quota-Bytes_resp:
description: |
If present, this is the limit on the total size in bytes of objects stored
in the account.
Typically this value is set by an administrator.
in: header
required: false
type: string
X-Account-Meta-Temp-URL-Key:
description: |
The secret key value for temporary URLs. If not
@ -311,6 +318,28 @@ X-Account-Object-Count:
in: header
required: true
type: integer
X-Account-Storage-Policy-name-Bytes-Used:
description: |
The total number of bytes that are stored in
in a given storage policy, where ``name`` is the
name of the storage policy.
in: header
required: true
type: integer
X-Account-Storage-Policy-name-Container-Count:
description: |
The number of containers in the account that use the given
storage policy where ``name`` is the name of the storage policy.
in: header
required: true
type: integer
X-Account-Storage-Policy-name-Object-Count:
description: |
The number of objects in given storage policy where ``name`` is
the name of the storage policy.
in: header
required: true
type: integer
X-Auth-Token:
description: |
Authentication token. If you omit this header,
@ -319,12 +348,6 @@ X-Auth-Token:
in: header
required: false
type: string
X-Auth-Token_1:
description: |
Authentication token.
in: header
required: true
type: string
X-Container-Bytes-Used:
description: |
The total number of bytes used.
@ -359,9 +382,9 @@ X-Container-Meta-Access-Control-Expose-Headers:
`http://www.w3.org/TR/cors/#simple-response-header
<http://www.w3.org/TR/cors/#simple-response-header>`_. - The
headers ``etag``, ``x-timestamp``, ``x-trans-id``. - All metadata
headers (``X-Container-Meta-*`` for containers and ``X-Object-
Meta-*`` for objects) headers listed in ``X-Container- Meta-
Access-Control-Expose-Headers``.
headers (``X-Container-Meta-*`` for containers and
``X-Object-Meta-*`` for objects) headers listed in
``X-Container-Meta-Access-Control-Expose-Headers``.
in: header
required: false
type: string
@ -376,28 +399,32 @@ X-Container-Meta-Access-Control-Max-Age:
type: string
X-Container-Meta-name:
description: |
The container metadata, where ``{name}`` is the
name of metadata item. You must specify an ``X-Container-Meta-
{name}`` header for each metadata item (for each ``{name}``) that
The custom container metadata item, where
``name`` is the name of the metadata item. One ``X-Container-Meta-name``
response header appears for each metadata item (for
each ``name``).
in: header
required: true
type: string
X-Container-Meta-name_req:
description: |
The container metadata, where ``name`` is the
name of metadata item. You must specify an ``X-Container-Meta-name``
header for each metadata item (for each ``name``) that
you want to add or update.
in: header
required: false
type: string
X-Container-Meta-name_1:
description: |
The custom container metadata item, where
``{name}`` is the name of the metadata item. One ``X-Container-
Meta- {name}`` response header appears for each metadata item (for
each ``{name}``).
in: header
required: true
type: string
X-Container-Meta-Quota-Bytes:
description: |
Sets maximum size of the container, in bytes.
Typically these values are set by an administrator. Returns a 413
response (request entity too large) when an object PUT operation
exceeds this quota value.
This value does not take effect immediately. see
`Container Quotas
<http://docs.openstack.org/developer/swift/api/container_quotas.html>`_
for more information.
in: header
required: false
type: string
@ -407,6 +434,10 @@ X-Container-Meta-Quota-Count:
Typically these values are set by an administrator. Returns a 413
response (request entity too large) when an object PUT operation
exceeds this quota value.
This value does not take effect immediately. see
`Container Quotas
<http://docs.openstack.org/developer/swift/api/container_quotas.html>`_
for more information.
in: header
required: false
type: string
@ -431,7 +462,7 @@ X-Container-Meta-Web-Directory-Type:
``application/directory``. Directory marker objects are 0-byte
objects that represent directories to create a simulated
hierarchical structure. For example, if you set ``"X-Container-
Meta-Web-Directory- Type: text/directory"``, Object Storage treats
Meta-Web-Directory-Type: text/directory"``, Object Storage treats
0-byte objects with a content-type of ``text/directory`` as
directories rather than objects.
in: header
@ -446,47 +477,18 @@ X-Container-Object-Count:
X-Container-Read:
description: |
Sets a container access control list (ACL) that grants read access.
Container ACLs are available on any Object Storage cluster, and are
enabled by container rather than by cluster.
The scope of the access is specific to the container. The ACL grants
the ability to perform GET or HEAD operations on objects in the container
or to perform a GET or HEAD operation on the container itself.
To set the container read ACL:
.. code-block:: bash
$ curl -X {PUT|POST} -i -H "X-Auth-Token: TOKEN" -H \
"X-Container-Read: ACL" STORAGE_URL/CONTAINER
For example:
.. code-block:: bash
$ curl -X PUT -i \
-H "X-Auth-Token: 0101010101" \
-H "X-Container-Read: .r:*" \
http://swift.example.com/v1/AUTH_bob/read_container
In the command, specify the ACL in the ``X-Container-Read`` header,
as follows:
- ``.r:*`` All referrers.
- ``.r:example.com,swift.example.com`` Comma-separated list of
referrers.
- ``.rlistings`` Container listing access.
- ``AUTH_username`` Access to a user who authenticates through a
legacy or non-OpenStack-Identity-based authentication system.
- ``LDAP_`` Access to all users who authenticate through an LDAP-
based legacy or non-OpenStack-Identity-based authentication
system.
The format and scope of the ACL is dependent on the authorization system
used by the Object Storage service.
in: header
required: false
type: string
X-Container-Read_1:
X-Container-Read_resp:
description: |
The ACL that grants read access. If not set, this
The ACL that grants read access. If there is no ACL, this
header is not returned by this operation.
in: header
required: false
@ -496,10 +498,13 @@ X-Container-Sync-Key:
Sets the secret key for container
synchronization. If you remove the secret key, synchronization is
halted.
For more information, see `Container to Container Synchronization
<http://docs.openstack.org/developer/swift/overview_
container_sync.html>`_
in: header
required: false
type: string
X-Container-Sync-Key_1:
X-Container-Sync-Key_resp:
description: |
The secret key for container synchronization. If
not set, this header is not returned by this operation.
@ -516,7 +521,7 @@ X-Container-Sync-To:
in: header
required: false
type: string
X-Container-Sync-To_1:
X-Container-Sync-To_resp:
description: |
The destination for container synchronization. If
not set, this header is not returned by this operation.
@ -525,13 +530,21 @@ X-Container-Sync-To_1:
type: string
X-Container-Write:
description: |
Sets an ACL that grants write access.
Sets a container access control list (ACL) that grants write access.
The scope of the access is specific to the container. The ACL grants
the ability to perform PUT, POST and DELETE operations on
objects in the container. It does not grant write access to the container
metadata.
The format of the ACL is dependent on the authorization system
used by the Object Storage service.
in: header
required: false
type: string
X-Container-Write_1:
description: |
The ACL that grants write access. If not set,
X-Container-Write_resp:
description:
The ACL that grants write access. If there is no ACL,
this header is not returned by this operation.
in: header
required: false
@ -544,6 +557,13 @@ X-Copied-From:
in: header
required: false
type: string
X-Copied-From-Account:
description: |
For a copied object, shows the account
from which the new object was copied.
in: header
required: false
type: string
X-Copied-From-Last-Modified:
description: |
For a copied object, the date and time in `UNIX
@ -572,7 +592,7 @@ X-Delete-After:
description: |
The number of seconds after which the system
removes the object. Internally, the Object Storage system stores
this value in the ``X -Delete-At`` metadata item.
this value in the ``X-Delete-At`` metadata item.
in: header
required: false
type: integer
@ -585,21 +605,11 @@ X-Delete-At:
in: header
required: false
type: integer
X-Delete-At_1:
description: |
If set, the date and time in `UNIX Epoch time
stamp format <https://en.wikipedia.org/wiki/Unix_time>`_ when the
system deletes the object. For example, ``1440619048`` is
equivalent to ``Mon, Wed, 26 Aug 2015 19:57:28 GMT``. If not set,
this operation does not return this header.
in: header
required: false
type: integer
X-Detect-Content-Type:
description: |
If set to ``true``, Object Storage guesses the
content type based on the file extension and ignores the value
sent in the ``Content- Type`` header, if present.
sent in the ``Content-Type`` header, if present.
in: header
required: false
type: boolean
@ -631,9 +641,9 @@ X-Object-Manifest:
in: header
required: false
type: string
X-Object-Manifest_1:
X-Object-Manifest_resp:
description: |
If set, to this is a dynamic large object
If present, this is a dynamic large object
manifest object. The value is the container and object name prefix
of the segment objects in the form ``container/prefix``.
in: header
@ -641,26 +651,35 @@ X-Object-Manifest_1:
type: string
X-Object-Meta-name:
description: |
The object metadata, where ``{name}`` is the name
of the metadata item. You must specify an ``X-Object-Meta-
{name}`` header for each metadata ``{name}`` item that you want to
add or update.
The object metadata, where ``name`` is the name
of the metadata item. You must specify an
``X-Object-Meta-name`` header for each metadata ``name`` item that
you want to add or update.
in: header
required: false
type: string
X-Object-Meta-name_1:
X-Object-Meta-name_resp:
description: |
The custom object metadata item, where ``{name}``
is the name of the metadata item. One ``X-Object-Meta- {name}``
response header appears for each metadata ``{name}`` item.
If present, the custom object metadata item, where ``name``
is the name of the metadata item. One``X-Object-Meta-name``
response header appears for each metadata ``name`` item.
in: header
required: true
required: false
type: string
X-Remove-Account-name:
description: |
Removes the metadata item named ``name``.
For example, ``X-Remove-Account-Meta-Blue`` removes
custom metadata.
in: header
required: false
type: string
X-Remove-Container-name:
description: |
Removes the metadata item named ``{name}``. For
example, ``X -Remove-Container-Read`` removes the ``X-Container-
Read`` metadata item.
Removes the metadata item named ``name``. For
example, ``X-Remove-Container-Read`` removes the
``X-Container-Read`` metadata item and ``X-Remove-Container-Meta-Blue``
removes custom metadata.
in: header
required: false
type: string
@ -670,6 +689,14 @@ X-Remove-Versions-Location:
in: header
required: false
type: string
X-Service-Token:
description: |
A service token. See `OpenStack Service Using Composite Tokens
<http://docs.openstack.org/developer/swift/overview_auth.html#openstack-
service-using-composite-tokens>`_ for more information.
in: header
required: false
type: string
X-Static-Large-Object:
description: |
Set to ``true`` if this object is a static large
@ -677,6 +704,14 @@ X-Static-Large-Object:
in: header
required: true
type: boolean
X-Storage-Policy:
description: |
In requests, specifies the name of the storage policy to use for
the container. In responses, is the storage policy name.
The storage policy of the container cannot be changed.
in: header
required: false
type: string
X-Timestamp:
description: |
The date and time in `UNIX Epoch time stamp
@ -696,23 +731,23 @@ X-Trans-Id:
type: string
X-Trans-Id-Extra:
description: |
Extra transaction information. Use the ``X-Trans-
Id-Extra`` request header to include extra information to help you
Extra transaction information. Use the ``X-Trans-Id-Extra``
request header to include extra information to help you
debug any errors that might occur with large object upload and
other Object Storage transactions. Object Storage appends the
first 32 characters of the ``X-Trans-Id- Extra`` request header
first 32 characters of the ``X-Trans-Id-Extra`` request header
value to the transaction ID value in the generated ``X-Trans-Id``
response header. You must UTF-8-encode and then URL-encode the
extra transaction information before you include it in the ``X
-Trans-Id-Extra`` request header. For example, you can include
extra transaction information when you upload `large objects
<http://docs.openstack.org/user-
guide/cli_swift_large_object_creation.html>`_ such as images. When
<http://docs.openstack.org/developer/swift/api/large_objects.html>`_
such as images. When
you upload each segment and the manifest, include the same value
in the ``X-Trans-Id-Extra`` request header. If an error occurs,
you can find all requests that are related to the large object
upload in the Object Storage logs. You can also use ``X-Trans-Id-
Extra`` strings to help operators debug requests that fail to
upload in the Object Storage logs. You can also use ``X-Trans-Id-Extra``
strings to help operators debug requests that fail to
receive responses. The operator can search for the extra
information in the logs.
in: header
@ -728,6 +763,16 @@ X-Versions-Location:
in: header
required: false
type: string
X-Versions-Location_resp:
description: |
If present, this container has versioning enabled and the value
is the UTF-8 encoded name of another container.
For more information about object versioning,
see `Object versioning <http://docs.openstack.org/developer/
swift/api/object_versioning.html>`_.
in: header
required: false
type: string
X-Versions-Mode:
description: |
The versioning mode for this container. The value must be either
@ -739,6 +784,15 @@ X-Versions-Mode:
in: header
required: false
type: string
X-Versions-Mode_resp:
description: |
If set, this is the versioning mode for this container. The value is either
``stack`` or ``history``. For more information about object versioning,
see `Object versioning <http://docs.openstack.org/developer/
swift/api/object_versioning.html>`_.
in: header
required: false
type: string
# variables in path
account:
@ -750,12 +804,13 @@ account:
type: string
container:
description: |
The unique name for the container. The container
The unique (within an account) name for the container. The container
name must be from 1 to 256 characters long and can start with any
character and contain any pattern. Character set must be UTF-8.
The container name cannot contain a slash (``/``) character
because this character delimits the container and object name. For
example, ``/account/container/object``.
example, the path ``/v1/account/www/pages`` specifies the ``www``
container, not the ``www/pages`` container.
in: path
required: false
type: string
@ -767,6 +822,16 @@ object:
type: string
# variables in query
bulk-delete:
description: |
When the ``bulk-delete`` query parameter is present in the POST
request, multiple objects or containers can be deleted
with a single request. See `Bulk Delete
<http://docs.openstack.org/developer/swift/middleware.html?highlight=
bulk#bulk-delete>`_ for how this feature is used.
in: query
required: false
type: string
delimiter:
description: |
Delimiter value, which returns the object names
@ -784,6 +849,16 @@ end_marker:
in: query
required: false
type: string
extract-archive:
description: |
When the ``extract-archive`` query parameter is present in the POST
request, an archive (tar file) is uploaded and extracted to
create multiple objects. See `Extract Archive
<http://docs.openstack.org/developer/swift/middleware.html?highlight=
bulk#extract-archive>`_ for how this feature is used.
in: query
required: false
type: string
filename:
description: |
Overrides the default file name. Object Storage
@ -823,23 +898,24 @@ marker:
in: query
required: false
type: string
multipart-manifest:
multipart-manifest_copy:
description: |
If ``?multipart-manifest=put``, the object is a
static large object manifest and the body contains the manifest.
If you include the ``multipart-manifest=get``
query parameter and the object is a large object, the object
contents are not copied. Instead, the manifest is copied to
the new object.
in: query
required: false
type: string
multipart-manifest_1:
multipart-manifest_delete:
description: |
If you include the ``multipart-manifest=delete``
query parameter and the object is a static large object, the
segment objects and manifest object are deleted. If you omit the
``multipart- manifest=delete`` query parameter and the object is a
``multipart-manifest=delete`` query parameter and the object is a
static large object, the manifest object is deleted but the
segment objects are not deleted. For a bulk delete, the response
body looks the same as it does for a normal bulk delete. In
contrast, a plain object DELETE response has an empty body.
segment objects are not deleted. The response body will contain
the status of the deletion of every processed segment object.
in: query
required: false
type: string
@ -862,6 +938,13 @@ multipart-manifest_head:
in: query
required: false
type: string
multipart-manifest_put:
description: |
If you include the ``multipart-manifest=put`` query parameter, the object
is a static large object manifest and the body contains the manifest.
in: query
required: false
type: string
path:
description: |
For a string value, returns the object names that
@ -878,11 +961,9 @@ prefix:
type: string
swiftinfo_expires:
description: |
Filters the response by the expiration date and
time in `UNIX Epoch time stamp format
<https://en.wikipedia.org/wiki/Unix_time>`_. For example,
``1440619048`` is equivalent to ``Mon, Wed, 26 Aug 2015 19:57:28
GMT``.
The time at which ``swiftinfo_sig`` expires. The time is in
`UNIX Epoch time stamp format
<https://en.wikipedia.org/wiki/Unix_time>`_.
in: query
required: false
type: integer

5
api-ref/source/samples/capabilities-list-response.json
View File

@ -2,6 +2,11 @@
"swift": {
"version": "1.11.0"
},
"slo": {
"max_manifest_segments": 1000,
"max_manifest_size": 2097152,
"min_segment_size": 1
},
"staticweb": {},
"tempurl": {}
}

160
api-ref/source/storage-account-services.inc
View File

@ -5,60 +5,10 @@ Accounts
========
Lists containers for an account. Creates, updates, shows, and
deletes account metadata.
deletes account metadata. For more information and concepts about
accounts see `Object Storage API overview
<http://docs.openstack.org/developer/swift/api/object_api_v1_overview.html>`_.
Account metadata operations work differently than container and
object metadata operations work. Depending on the contents of your
POST account metadata request, the Object Storage API updates the
metadata in one of these ways:
**Account metadata operations**
+----------------------------------------------------------+---------------------------------------------------------------+
| POST request body contains | Description |
+----------------------------------------------------------+---------------------------------------------------------------+
| A metadata key without a value. | The API removes the metadata item from the account. |
| | |
| The metadata key already exists for the account. | |
+----------------------------------------------------------+---------------------------------------------------------------+
| A metadata key without a value. | The API ignores the metadata key. |
| | |
| The metadata key does not already exist for the account. | |
+----------------------------------------------------------+---------------------------------------------------------------+
| A metadata key value. | The API updates the metadata key value for the account. |
| | |
| The metadata key already exists for the account. | |
+----------------------------------------------------------+---------------------------------------------------------------+
| A metadata key value. | The API adds the metadata key and value pair, or item, to the |
| | account. |
| The metadata key does not already exist for the account. | |
+----------------------------------------------------------+---------------------------------------------------------------+
| One or more account metadata items are omitted. | The API does not change the existing metadata items. |
| | |
| The metadata items already exist for the account. | |
+----------------------------------------------------------+---------------------------------------------------------------+
For these requests, specifying the ``X-Remove-Account-Meta-*``
request header for the key with any value is equivalent to
specifying the ``X-Account-Meta-*`` request header with an empty
value.
Metadata keys must be treated as case-insensitive at all times.
These keys can contain ASCII 7-bit characters that are not control
(0-31) characters, DEL, or a separator character, according to
`HTTP/1.1 <http://www.w3.org/Protocols/rfc2616/rfc2616.html>`_ .
Also, Object Storage does not support the underscore character,
which it silently converts to a hyphen.
The metadata values in Object Storage do not follow HTTP/1.1 rules
for character encodings. You must use a UTF-8 encoding to get a
byte array for any string that contains characters that are not in
the 7-bit ASCII 0-127 range. Otherwise, Object Storage returns the
404 response code for ISO-8859-1 characters in the 128-255 range,
which is a direct violation of the HTTP/1.1 `basic rules
<http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2>`_.
Show account details and list containers
@ -135,6 +85,7 @@ Request
- prefix: prefix
- delimiter: delimiter
- X-Auth-Token: X-Auth-Token
- X-Service-Token: X-Service-Token
- X-Newest: X-Newest
- Accept: Accept
- X-Trans-Id-Extra: X-Trans-Id-Extra
@ -145,30 +96,39 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- Content-Length: Content-Length
- Content-Length: Content-Length_listing_resp
- X-Account-Meta-name: X-Account-Meta-name
- X-Account-Object-Count: X-Account-Object-Count
- X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key
- X-Account-Meta-Temp-URL-Key-2: X-Account-Meta-Temp-URL-Key-2
- X-Timestamp: X-Timestamp
- X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key
- X-Trans-Id: X-Trans-Id
- Date: Date
- X-Account-Bytes-Used: X-Account-Bytes-Used
- X-Account-Container-Count: X-Account-Container-Count
- Content-Type: Content-Type
- X-Account-Object-Count: X-Account-Object-Count
- X-Account-Storage-Policy-name-Bytes-Used: X-Account-Storage-Policy-name-Bytes-Used
- X-Account-Storage-Policy-name-Container-Count: X-Account-Storage-Policy-name-Container-Count
- X-Account-Storage-Policy-name-Object-Count: X-Account-Storage-Policy-name-Object-Count
- X-Account-Meta-Quota-Bytes: X-Account-Meta-Quota-Bytes_resp
- Content-Type: Content-Type_listing_resp
- count: count
- bytes: bytes
- name: name
Response Example
----------------
Response Example format=json
----------------------------
.. literalinclude:: samples/account-containers-list-http-response-json.txt
.. literalinclude:: samples/account-containers-list-response.json
Response Example format=xml
---------------------------
.. literalinclude:: samples/account-containers-list-http-response-xml.txt
:language: javascript
.. literalinclude:: samples/account-containers-list-response.xml
@ -179,21 +139,62 @@ Create, update, or delete account metadata
Creates, updates, or deletes account metadata.
To create, update, or delete metadata, use the ``X-Account-
Meta-{name}`` request header, where ``{name}`` is the name of the
To create, update, or delete custom metadata, use the
``X-Account-Meta-{name}`` request header, where ``{name}`` is the name of the
metadata item.
Subsequent requests for the same key and value pair overwrite the
existing value.
Account metadata operations work differently than how
object metadata operations work. Depending on the contents of your
POST account metadata request, the Object Storage API updates the
metadata as shown in the following table:
**Account metadata operations**
+----------------------------------------------------------+---------------------------------------------------------------+
| POST request header contains | Result |
+----------------------------------------------------------+---------------------------------------------------------------+
| A metadata key without a value. | The API removes the metadata item from the account. |
| | |
| The metadata key already exists for the account. | |
+----------------------------------------------------------+---------------------------------------------------------------+
| A metadata key without a value. | The API ignores the metadata key. |
| | |
| The metadata key does not already exist for the account. | |
+----------------------------------------------------------+---------------------------------------------------------------+
| A metadata key value. | The API updates the metadata key value for the account. |
| | |
| The metadata key already exists for the account. | |
+----------------------------------------------------------+---------------------------------------------------------------+
| A metadata key value. | The API adds the metadata key and value pair, or item, to the |
| | account. |
| The metadata key does not already exist for the account. | |
+----------------------------------------------------------+---------------------------------------------------------------+
| One or more account metadata items are omitted. | The API does not change the existing metadata items. |
| | |
| The metadata items already exist for the account. | |
+----------------------------------------------------------+---------------------------------------------------------------+
To delete a metadata header, send an empty value for that header,
such as for the ``X-Account-Meta-Book`` header. If the tool you use
to communicate with Object Storage, such as an older version of
cURL, does not support empty headers, send the ``X-Remove-Account-
Meta-{name}`` header with an arbitrary value. For example, ``X
-Remove-Account-Meta-Book: x``. The operation ignores the arbitrary
Meta-{name}`` header with an arbitrary value. For example,
``X-Remove-Account-Meta-Book: x``. The operation ignores the arbitrary
value.
Metadata keys (the name of the metadata) must be treated as case-insensitive
at all times. These keys can contain ASCII 7-bit characters that are not
control (0-31) characters, DEL, or a separator character, according to
`HTTP/1.1 <http://www.w3.org/Protocols/rfc2616/rfc2616.html>`_ .
The underscore character is silently converted to a hyphen.
.. include:: metadata_header_encoding.inc
Subsequent requests for the same key and value pair overwrite the
existing value.
If the container already has other custom metadata items, a request
to create, update, or delete metadata does not affect those items.
@ -270,11 +271,11 @@ Request
- account: account
- X-Auth-Token: X-Auth-Token
- X-Service-Token: X-Service-Token
- X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key
- X-Account-Meta-Temp-URL-Key-2: X-Account-Meta-Temp-URL-Key-2
- X-Account-Meta-name: X-Account-Meta-name
- Content-Type: Content-Type
- X-Detect-Content-Type: X-Detect-Content-Type
- X-Account-Meta-name: X-Account-Meta-name_req
- X-Remove-Account-name: X-Remove-Account-name
- X-Trans-Id-Extra: X-Trans-Id-Extra
@ -285,8 +286,8 @@ Response Parameters
- Date: Date
- X-Timestamp: X-Timestamp
- Content-Length: Content-Length
- Content-Type: Content-Type
- Content-Length: Content-Length_cud_resp
- Content-Type: Content-Type_cud_resp
- X-Trans-Id: X-Trans-Id
@ -353,6 +354,7 @@ Request
- account: account
- X-Auth-Token: X-Auth-Token
- X-Service-Token: X-Service-Token
- X-Newest: X-Newest
- X-Trans-Id-Extra: X-Trans-Id-Extra
@ -362,17 +364,21 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- Content-Length: Content-Length
- Content-Length: Content-Length_cud_resp
- X-Account-Meta-name: X-Account-Meta-name
- X-Account-Object-Count: X-Account-Object-Count
- X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key
- X-Account-Meta-Temp-URL-Key-2: X-Account-Meta-Temp-URL-Key-2
- X-Timestamp: X-Timestamp
- X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key
- X-Trans-Id: X-Trans-Id
- Date: Date
- X-Account-Bytes-Used: X-Account-Bytes-Used
- X-Account-Object-Count: X-Account-Object-Count
- X-Account-Container-Count: X-Account-Container-Count
- Content-Type: Content-Type
- X-Account-Storage-Policy-name-Bytes-Used: X-Account-Storage-Policy-name-Bytes-Used
- X-Account-Storage-Policy-name-Container-Count: X-Account-Storage-Policy-name-Container-Count
- X-Account-Storage-Policy-name-Object-Count: X-Account-Storage-Policy-name-Object-Count
- X-Account-Meta-Quota-Bytes: X-Account-Meta-Quota-Bytes_resp
- Content-Type: Content-Type_cud_resp

141
api-ref/source/storage-container-services.inc
View File

@ -6,7 +6,9 @@ Containers
Lists objects in a container. Creates, shows details for, and
deletes containers. Creates, updates, shows, and deletes container
metadata.
metadata. For more information and concepts about
containers see `Object Storage API overview
<http://docs.openstack.org/developer/swift/api/object_api_v1_overview.html>`_.
Show container details and list objects
@ -17,8 +19,8 @@ Show container details and list objects
Shows details for a container and lists objects, sorted by name, in the container.
Specify query parameters in the request to filter the list and
return a subset of object names. Omit query parameters to return
the complete list of object names that are stored in the container,
return a subset of objects. Omit query parameters to return
a list of objects that are stored in the container,
up to 10,000 names. The 10,000 maximum value is configurable. To
view the value for the cluster, issue a GET ``/info`` request.
@ -28,23 +30,13 @@ Example requests and responses:
- ``No Content (204)``. Success. The response body shows no objects.
Either the container has no objects or you are paging through a
long list of names by using the ``marker``, ``limit``, or
long list of objects by using the ``marker``, ``limit``, or
``end_marker`` query parameter and you have reached the end of
the list.
If the container does not exist, the call returns the ``Not Found
(404)`` response code.
The operation returns the ``Range Not Satisfiable (416)`` response
code for any ranged GET requests that specify more than:
- Fifty ranges.
- Three overlapping ranges.
- Eight non-increasing ranges.
Normal response codes: 200
Error response codes:416,404,204,
@ -64,11 +56,13 @@ Request
- delimiter: delimiter
- path: path
- X-Auth-Token: X-Auth-Token
- X-Service-Token: X-Service-Token
- X-Newest: X-Newest
- Accept: Accept
- X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key
- X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2
- X-Trans-Id-Extra: X-Trans-Id-Extra
- X-Storage-Policy: X-Storage-Policy
Response Parameters
@ -77,35 +71,42 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- X-Container-Meta-name: X-Container-Meta-name
- Content-Length: Content-Length
- Content-Length: Content-Length_listing_resp
- X-Container-Object-Count: X-Container-Object-Count
- X-Container-Bytes-Used: X-Container-Bytes-Used
- Accept-Ranges: Accept-Ranges
- X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key
- X-Container-Bytes-Used: X-Container-Bytes-Used
- X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2
- X-Storage-Policy: X-Storage-Policy
- X-Container-Read: X-Container-Read_resp
- X-Container-Write: X-Container-Write_resp
- X-Container-Sync-Key: X-Container-Sync-Key_resp
- X-Container-Sync-To: X-Container-Sync-To_resp
- X-Versions-Location: X-Versions-Location_resp
- X-Versions-Mode: X-Versions-Mode_resp
- X-Timestamp: X-Timestamp
- X-Trans-Id: X-Trans-Id
- Content_Type: Content-Type_listing_resp
- Date: Date
- Content-Type: Content-Type
- hash: hash
- last_modified: last_modified
- content_type: content_type
- bytes: bytes
- name: name
- content_type: content_type
Response Example format=json
----------------------------
Response Example
----------------
.. literalinclude:: samples/objects-list-http-response-json.txt
.. literalinclude:: samples/objects-list-response.json
Response Example format=xml
---------------------------
.. literalinclude:: samples/objects-list-http-response-xml.txt
:language: javascript
.. literalinclude:: samples/objects-list-response.xml
Create container
================
@ -119,6 +120,18 @@ issuing a PUT operation because the operation is idempotent: It
creates a container or updates an existing container, as
appropriate.
To create, update, or delete a custom metadata item, use the ``X
-Container-Meta-{name}`` header, where ``{name}`` is the name of
the metadata item.
Metadata keys (the name of the metadata) must be treated as case-insensitive
at all times. These keys can contain ASCII 7-bit characters that are not
control (0-31) characters, DEL, or a separator character, according to
`HTTP/1.1 <http://www.w3.org/Protocols/rfc2616/rfc2616.html>`_ .
The underscore character is silently converted to a hyphen.
.. include:: metadata_header_encoding.inc
Example requests and responses:
- Create a container with no metadata:
@ -148,6 +161,22 @@ Example requests and responses:
::
HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37
Date: Tue, 14 Jan 2014 19:25:43 GMT
- Create a container with an ACL to allow anybody to get an object in the
marktwain container:
::
curl -i $publicURL/marktwain -X PUT -H "X-Auth-Token: $token" -H "X-Container-Read: .r:*"
::
HTTP/1.1 201 Created
@ -167,21 +196,21 @@ Request
- account: account
- container: container
- X-Auth-Token: X-Auth-Token
- X-Service-Token: X-Service-Token
- X-Container-Read: X-Container-Read
- X-Container-Write: X-Container-Write
- X-Container-Sync-To: X-Container-Sync-To
- X-Container-Sync-Key: X-Container-Sync-Key
- X-Versions-Location: X-Versions-Location
- X-Versions-Mode: X-Versions-Mode
- X-Container-Meta-name: X-Container-Meta-name
- X-Container-Meta-name: X-Container-Meta-name_req
- X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin
- X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age
- X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers
- Content-Type: Content-Type
- X-Detect-Content-Type: X-Detect-Content-Type
- X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key
- X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2
- X-Trans-Id-Extra: X-Trans-Id-Extra
- X-Storage-Policy: X-Storage-Policy
Response Parameters
@ -191,8 +220,8 @@ Response Parameters
- Date: Date
- X-Timestamp: X-Timestamp
- Content-Length: Content-Length
- Content-Type: Content-Type
- Content-Length: Content-Length_cud_resp
- Content-Type: Content-Type_cud_resp
- X-Trans-Id: X-Trans-Id
@ -211,6 +240,14 @@ To create, update, or delete a custom metadata item, use the ``X
-Container-Meta-{name}`` header, where ``{name}`` is the name of
the metadata item.
Metadata keys (the name of the metadata) must be treated as case-insensitive
at all times. These keys can contain ASCII 7-bit characters that are not
control (0-31) characters, DEL, or a separator character, according to
`HTTP/1.1 <http://www.w3.org/Protocols/rfc2616/rfc2616.html>`_ .
The underscore character is silently converted to a hyphen.
.. include:: metadata_header_encoding.inc
Subsequent requests for the same key and value pair overwrite the
previous value.
@ -297,6 +334,7 @@ Request
- account: account
- container: container
- X-Auth-Token: X-Auth-Token
- X-Service-Token: X-Service-Token
- X-Container-Read: X-Container-Read
- X-Remove-Container-name: X-Remove-Container-name
- X-Container-Write: X-Container-Write
@ -305,15 +343,13 @@ Request
- X-Versions-Location: X-Versions-Location
- X-Versions-Mode: X-Versions-Mode
- X-Remove-Versions-Location: X-Remove-Versions-Location
- X-Container-Meta-name: X-Container-Meta-name
- X-Container-Meta-name: X-Container-Meta-name_req
- X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin
- X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age
- X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers
- X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes
- X-Container-Meta-Quota-Count: X-Container-Meta-Quota-Count
- X-Container-Meta-Web-Directory-Type: X-Container-Meta-Web-Directory-Type
- Content-Type: Content-Type
- X-Detect-Content-Type: X-Detect-Content-Type
- X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key
- X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2
- X-Trans-Id-Extra: X-Trans-Id-Extra
@ -326,8 +362,8 @@ Response Parameters
- Date: Date
- X-Timestamp: X-Timestamp
- Content-Length: Content-Length
- Content-Type: Content-Type
- Content-Length: Content-Length_cud_resp
- Content-Type: Content-Type_cud_resp
- X-Trans-Id: X-Trans-Id
@ -379,9 +415,8 @@ Request
- account: account
- container: container
- X-Auth-Token: X-Auth-Token
- X-Service-Token: X-Service-Token
- X-Newest: X-Newest
- X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key
- X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2
- X-Trans-Id-Extra: X-Trans-Id-Extra
@ -390,28 +425,29 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- X-Container-Sync-Key: X-Container-Sync-Key
- X-Container-Meta-name: X-Container-Meta-name
- Content-Length: Content-Length
- Content-Length: Content-Length_cud_resp
- X-Container-Object-Count: X-Container-Object-Count
- X-Container-Write: X-Container-Write
- X-Container-Bytes-Used: X-Container-Bytes-Used
- X-Container-Write: X-Container-Write_resp
- X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes
- X-Container-Meta-Quota-Count: X-Container-Meta-Quota-Count
- Accept-Ranges: Accept-Ranges
- X-Container-Read: X-Container-Read
- X-Container-Read: X-Container-Read_resp
- X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers
- X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key
- X-Container-Bytes-Used: X-Container-Bytes-Used
- X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2
- X-Timestamp: X-Timestamp
- X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin
- X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age
- X-Container-Sync-Key: X-Container-Sync-Key_resp
- X-Container-Sync-To: X-Container-Sync-To_resp
- Date: Date
- X-Trans-Id: X-Trans-Id
- X-Container-Sync-To: X-Container-Sync-To
- Content-Type: Content-Type
- X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes
- X-Versions-Location: X-Versions-Location
- X-Versions-Mode: X-Versions-Mode
- Content-Type: Content-Type_cud_resp
- X-Versions-Location: X-Versions-Location_resp
- X-Versions-Mode: X-Versions-Mode_resp
- X-Storage-Policy: X-Storage-Policy
@ -483,8 +519,7 @@ Request
- account: account
- container: container
- X-Auth-Token: X-Auth-Token
- X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key
- X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2
- X-Service-Token: X-Service-Token
- X-Trans-Id-Extra: X-Trans-Id-Extra
@ -495,8 +530,8 @@ Response Parameters
- Date: Date
- X-Timestamp: X-Timestamp
- Content-Length: Content-Length
- Content-Type: Content-Type
- Content-Length: Content-Length_cud_resp
- Content-Type: Content-Type_cud_resp
- X-Trans-Id: X-Trans-Id

179
api-ref/source/storage-object-services.inc
View File

@ -6,7 +6,11 @@ Objects
Creates, replaces, shows details for, and deletes objects. Copies
objects from another object with a new or different name. Updates
object metadata.
object metadata. For more information and concepts about
objects see `Object Storage API overview
<http://docs.openstack.org/developer/swift/api/object_api_v1_overview.html>`_
and `Large Objects
<http://docs.openstack.org/developer/swift/api/large_objects.html>`_.
Get object content and metadata
@ -96,9 +100,10 @@ Request
.. rest_parameters:: parameters.yaml
- account: account
- object: object
- container: container
- object: object
- X-Auth-Token: X-Auth-Token
- X-Service-Token: X-Service-Token
- X-Newest: X-Newest
- temp_url_sig: temp_url_sig
- temp_url_expires: temp_url_expires
@ -117,20 +122,20 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- Content-Length: Content-Length
- X-Object-Meta-name: X-Object-Meta-name
- Content-Disposition: Content-Disposition
- Content-Encoding: Content-Encoding
- Content-Length: Content-Length_get_resp
- Content-Type: Content-Type_obj_resp
- X-Object-Meta-name: X-Object-Meta-name_resp
- Content-Disposition: Content-Disposition_resp
- Content-Encoding: Content-Encoding_resp
- X-Delete-At: X-Delete-At
- Accept-Ranges: Accept-Ranges
- X-Object-Manifest: X-Object-Manifest
- X-Object-Manifest: X-Object-Manifest_resp
- Last-Modified: Last-Modified
- ETag: ETag
- ETag: ETag_obj_resp
- X-Timestamp: X-Timestamp
- X-Trans-Id: X-Trans-Id
- Date: Date
- X-Static-Large-Object: X-Static-Large-Object
- Content-Type: Content-Type
@ -157,6 +162,16 @@ is a normal object and not a copy of the manifest. Instead it is a
concatenation of all the segment objects. This means that you
cannot copy objects larger than 5 GB.
To create custom metadata, use the
``X-Object-Meta-name`` header, where ``name`` is the name of the metadata
item.
Metadata keys (the name of the metadata) must be treated as case-insensitive
at all times. These keys can contain ASCII 7-bit characters that are not
control (0-31) characters, DEL, or a separator character, according to
`HTTP/1.1 <http://www.w3.org/Protocols/rfc2616/rfc2616.html>`_ .
The underscore character is silently converted to a hyphen.
Example requests and responses:
- Create object:
@ -220,20 +235,20 @@ Request
.. rest_parameters:: parameters.yaml
- account: account
- object: object
- container: container
- multipart-manifest: multipart-manifest
- object: object
- multipart-manifest: multipart-manifest_put
- temp_url_sig: temp_url_sig
- temp_url_expires: temp_url_expires
- filename: filename
- X-Object-Manifest: X-Object-Manifest
- X-Auth-Token: X-Auth-Token
- Content-Length: Content-Length
- X-Service-Token: X-Service-Token
- Content-Length: Content-Length_put_req
- Transfer-Encoding: Transfer-Encoding
- Content-Type: Content-Type
- Content-Type: Content-Type_obj_cu_req
- X-Detect-Content-Type: X-Detect-Content-Type
- X-Copy-From: X-Copy-From
- ETag: ETag
- ETag: ETag_obj_req
- Content-Disposition: Content-Disposition
- Content-Encoding: Content-Encoding
- X-Delete-At: X-Delete-At
@ -248,12 +263,12 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- Content-Length: Content-Length
- ETag: ETag
- Content-Length: Content-Length_cud_resp
- ETag: ETag_obj_received
- X-Timestamp: X-Timestamp
- X-Trans-Id: X-Trans-Id
- Date: Date
- Content-Type: Content-Type
- Content-Type: Content-Type_obj_resp
- last_modified: last_modified
@ -272,25 +287,33 @@ Copies an object to another object in the object store.
You can copy an object to a new object with the same name. Copying
to the same name is an alternative to using POST to add metadata to
an object. With POST , you must specify all the metadata. With COPY
, you can add additional metadata to the object.
an object. With POST, you must specify all the metadata. With COPY,
you can add additional metadata to the object.
With COPY , you can set the ``X-Fresh-Metadata`` header to ``true``
With COPY, you can set the ``X-Fresh-Metadata`` header to ``true``
to copy the object without any existing metadata.
Alternatively, you can use PUT with the ``X-Copy-From`` request
header to accomplish the same operation as the COPY object
operation.
The PUT operation always creates an object. If you use this
The COPY operation always creates an object. If you use this
operation on an existing object, you replace the existing object
and metadata rather than modifying the object. Consequently, this
operation returns the ``Created (201)`` response code.
If you use this operation to copy a manifest object, the new object
Normally, if you use this operation to copy a manifest object, the new object
is a normal object and not a copy of the manifest. Instead it is a
concatenation of all the segment objects. This means that you
cannot copy objects larger than 5 GB in size. All metadata is
cannot copy objects larger than 5 GB in size.
To copy the manifest object, you include the
``multipart-manifest=get`` query string in the COPY request.
The new object contains the same manifest as the original.
The segment objects are not copied. Instead, both the original
and new manifest objects share the same set of segment objects.
All metadata is
preserved during the object copy. If you specify metadata on the
request to copy the object, either PUT or COPY , the metadata
overwrites any conflicting keys on the target (new) object.
@ -360,11 +383,14 @@ Request
.. rest_parameters:: parameters.yaml
- account: account
- object: object
- container: container
- object: object
- multipart-manifest: multipart-manifest_copy
- X-Auth-Token: X-Auth-Token
- X-Service-Token: X-Service-Token
- Destination: Destination
- Content-Type: Content-Type
- Destination-Account: Destination-Account
- Content-Type: Content-Type_obj_cu_req
- Content-Encoding: Content-Encoding
- Content-Disposition: Content-Disposition
- X-Object-Meta-name: X-Object-Meta-name
@ -377,16 +403,16 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- Content-Length: Content-Length
- X-Object-Meta-name: X-Object-Meta-name
- Content-Length: Content-Length_cud_resp
- X-Copied-From-Last-Modified: X-Copied-From-Last-Modified
- X-Copied-From: X-Copied-From
- X-Copied-From-Account: X-Copied-From-Account
- Last-Modified: Last-Modified
- ETag: ETag
- ETag: ETag_obj_copied
- X-Timestamp: X-Timestamp
- X-Trans-Id: X-Trans-Id
- Date: Date
- Content-Type: Content-Type
- Content-Type: Content-Type_obj_resp
@ -399,18 +425,18 @@ Delete object
Permanently deletes an object from the object store.
You can use the COPY method to copy the object to a new location.
Then, use the DELETE method to delete the original object.
Object deletion occurs immediately at request time. Any subsequent
GET , HEAD , POST , or DELETE operations return a ``404 Not Found``
GET, HEAD, POST, or DELETE operations will return a ``404 Not Found``
error code.
For static large object manifests, you can add the ``?multipart-
manifest=delete`` query parameter. This operation deletes the
segment objects and if all deletions succeed, this operation
segment objects and, if all deletions succeed, this operation
deletes the manifest object.
An alternative to using the DELETE operation is to use
the POST operation with the ``bulk-delete`` query parameter.
Example request and response:
- Delete the ``helloworld`` object from the ``marktwain`` container:
@ -445,10 +471,11 @@ Request
.. rest_parameters:: parameters.yaml
- account: account
- object: object
- container: container
- multipart-manifest: multipart-manifest
- object: object
- multipart-manifest: multipart-manifest_delete
- X-Auth-Token: X-Auth-Token
- X-Service-Token: X-Service-Token
- X-Trans-Id-Extra: X-Trans-Id-Extra
@ -459,8 +486,8 @@ Response Parameters
- Date: Date
- X-Timestamp: X-Timestamp
- Content-Length: Content-Length
- Content-Type: Content-Type
- Content-Length: Content-Length_cud_resp
- Content-Type: Content-Type_cud_resp
- X-Trans-Id: X-Trans-Id
@ -474,10 +501,7 @@ Show object metadata
Shows object metadata.
If the ``Content-Length`` response header is non-zero, the example
cURL command stalls after it prints the response headers because it
is waiting for a response body. However, the Object Storage system
does not return a response body for the HEAD operation.
Example requests and responses:
@ -485,7 +509,7 @@ Example requests and responses:
::
curl -i $publicURL/marktwain/goodbye -X HEAD -H "X-Auth-Token: $token"
curl $publicURL/marktwain/goodbye --head -H "X-Auth-Token: $token"
@ -503,6 +527,12 @@ Example requests and responses:
X-Trans-Id: tx37ea34dcd1ed48ca9bc7d-0052d84b6f
Date: Thu, 16 Jan 2014 21:13:19 GMT
Note: The ``--head`` option was used in the above example. If we had
used ``-i -X HEAD`` and the ``Content-Length`` response header is non-zero,
the cURL command stalls after it prints the response headers because it
is waiting for a response body. However, the Object Storage system
does not return a response body for the HEAD operation.
If the request succeeds, the operation returns the ``200`` response
code.
@ -518,9 +548,10 @@ Request
.. rest_parameters:: parameters.yaml
- account: account
- object: object
- container: container
- object: object
- X-Auth-Token: X-Auth-Token
- X-Service-Token: X-Service-Token
- temp_url_sig: temp_url_sig
- temp_url_expires: temp_url_expires
- filename: filename
@ -534,20 +565,19 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- Last-Modified: Last-Modified
- Content-Length: Content-Length
- Content-Length: Content-Length_obj_head_resp
- X-Object-Meta-name: X-Object-Meta-name
- Content-Disposition: Content-Disposition
- Content-Encoding: Content-Encoding
- Content-Disposition: Content-Disposition_resp
- Content-Encoding: Content-Encoding_resp
- X-Delete-At: X-Delete-At
- X-Object-Manifest: X-Object-Manifest
- X-Object-Manifest: X-Object-Manifest_resp
- Last-Modified: Last-Modified
- ETag: ETag
- ETag: ETag_obj_resp
- X-Timestamp: X-Timestamp
- X-Trans-Id: X-Trans-Id
- Date: Date
- X-Static-Large-Object: X-Static-Large-Object
- Content-Type: Content-Type
- Content-Type: Content-Type_obj_resp
@ -565,20 +595,25 @@ Create or update object metadata
Creates or updates object metadata.
To create or update custom metadata, use the ``X-Object-
Meta-{name}`` header, where ``{name}`` is the name of the metadata
To create or update custom metadata, use the
``X-Object-Meta-name`` header, where ``name`` is the name of the metadata
item.
In addition to the custom metadata, you can update the ``Content-
Type``, ``Content-Encoding``, ``Content-Disposition``, and ``X
-Delete-At`` system metadata items. However you cannot update other
Metadata keys (the name of the metadata) must be treated as case-insensitive
at all times. These keys can contain ASCII 7-bit characters that are not
control (0-31) characters, DEL, or a separator character, according to
`HTTP/1.1 <http://www.w3.org/Protocols/rfc2616/rfc2616.html>`_ .
The underscore character is silently converted to a hyphen.
In addition to the custom metadata, you can update the
``Content-Type``, ``Content-Encoding``, ``Content-Disposition``, and
``X-Delete-At`` system metadata items. However you cannot update other
system metadata, such as ``Content-Length`` or ``Last-Modified``.
You can use COPY as an alternate to the POST operation by copying
to the same object. With the POST operation you must specify all
metadata items, whereas with the COPY operation, you need to
specify only changed or additional items.
All metadata is preserved during the object copy. If you specify
metadata on the request to copy the object, either PUT or COPY ,
the metadata overwrites any conflicting keys on the target (new)
@ -595,11 +630,19 @@ to define when to expire the object.
When used as described in this section, the POST operation creates
or replaces metadata. This form of the operation has no request
body.
body. There are alternate uses of the POST operation as follows:
You can also use the `form POST feature
<http://docs.openstack.org/liberty/config-reference/content/object-
storage-form-post.html>`_ to upload objects.
- You can also use the `form POST feature
<http://docs.openstack.org/liberty/config-reference/content/object-
storage-form-post.html>`_ to upload objects.
- The POST operation when used with the ``bulk-delete`` query parameter
can be used to delete multiple objects and containers in a single
operation.
- The POST operation when used with the ``extract-archive`` query parameter
can be used to upload an archive (tar file). The archive is then extracted
to create objects.
Example requests and responses:
@ -659,16 +702,18 @@ Request
.. rest_parameters:: parameters.yaml
- account: account
- object: object
- container: container
- object: object
- bulk-delete: bulk-delete
- extract-archive: extract-archive
- X-Auth-Token: X-Auth-Token
- X-Service-Token: X-Service-Token
- X-Object-Meta-name: X-Object-Meta-name
- X-Delete-At: X-Delete-At
- Content-Disposition: Content-Disposition
- Content-Encoding: Content-Encoding
- X-Delete-After: X-Delete-After
- Content-Type: Content-Type
- X-Detect-Content-Type: X-Detect-Content-Type
- Content-Type: Content-Type_obj_cu_req
- X-Trans-Id-Extra: X-Trans-Id-Extra
@ -679,8 +724,8 @@ Response Parameters
- Date: Date
- X-Timestamp: X-Timestamp
- Content-Length: Content-Length
- Content-Type: Content-Type
- Content-Length: Content-Length_cud_resp
- Content-Type: Content-Type_cud_resp
- X-Trans-Id: X-Trans-Id

5
api-ref/source/storage_info.inc
View File

@ -15,6 +15,11 @@ List activated capabilities
Lists the activated capabilities for this version of the OpenStack Object Storage API.
Most of the information is "public" i.e. visible to all callers. However, some
configuration and capability items are reserved for the administrators of the
system. To access this data, the ``swiftinfo_sig`` and ``swiftinfo_expires``
query parameters must be added to the request.
Normal response codes: 200
Error response codes: