openstack/api-site
Code Issues Proposed changes

Removes Object Storage files and adds redirect

Browse Source 
Change-Id: I523ea979ea98703e04eaa60d64817fe8703a9e22
This commit is contained in:
Anne Gentle 2016-08-10 15:38:45 -05:00 committed by Andreas Jaeger
parent f8546708fa
commit bc1fc77fa2
50 changed files with 3 additions and 6312 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
api-ref-guides/pom.xml
View File

@ -105,17 +105,6 @@
<pdfFilenameBase>api-ref-data-processing-v1.1</pdfFilenameBase>
</configuration>
</execution>
<execution>
<id>os-api-ref-objectstorage-v1</id>
<goals>
<goal>generate-pdf</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<includes> bk-api-ref-objectstorage-v1.xml </includes>
<pdfFilenameBase>api-ref-objectstorage-v1</pdfFilenameBase>
</configuration>
</execution>
<execution>
<id>os-api-ref-share-v2</id>
<goals>

37
api-ref-guides/src/bk-api-ref-objectstorage-v1.xml
View File

@ -1,37 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:linkend="http://www.w3.org/1999/linkend"
xmlns:xref="http://www.w3.org/1999/xref"
xmlns:wadl="http://wadl.dev.java.net/2009/02"
version="5.0-extension RackBook-2.0"
xml:id="api.openstack.org-objectstorage-pdf">
<info>
<title>OpenStack Object Storage API v1 Reference</title>
<titleabbrev>API Reference</titleabbrev>
<author>
<personname>
<firstname/>
<surname/>
</personname>
<affiliation>
<orgname>OpenStack Foundation</orgname>
</affiliation>
</author>
<copyright>
<year>2010-2016</year>
<holder>OpenStack Foundation</holder>
</copyright>
<productname>OpenStack Object Storage</productname>
<pubdate/>
<legalnotice role="apache2">
<annotation>
<remark>Copyright details are filled in by the
template.</remark>
</annotation>
</legalnotice>
</info>
<xi:include
href="../../api-ref/src/docbkx/ch_objectstorage-v1.xml"/>
</book>

1
api-ref-guides/src/bk-api-ref.xml
View File

@ -37,7 +37,6 @@
<xi:include href="../../api-ref/src/docbkx/ch_blockstorage-api-v1.xml"/>
<xi:include href="../../api-ref/src/docbkx/ch_database-v1.xml"/>
<xi:include href="../../api-ref/src/docbkx/ch_data-processing-v1.1.xml"/>
<xi:include href="../../api-ref/src/docbkx/ch_objectstorage-v1.xml"/>
<xi:include href="../../api-ref/src/docbkx/ch_share-v2.xml"/>
<xi:include href="../../api-ref/src/docbkx/ch_share-v1.xml"/>
<xi:include href="../../api-ref/src/docbkx/ch_telemetry-v2.xml"/>

11
api-ref/pom.xml
View File

@ -113,17 +113,6 @@
<pdfFilename>bk-api-ref-database-v1</pdfFilename>
</configuration>
</execution>
<execution>
<id>os-api-ref-objectstorage-v1</id>
<goals>
<goal>generate-html</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<includes>api-ref-objectstorage-v1.xml </includes>
<pdfFilename>bk-api-ref-objectstorage-v1</pdfFilename>
</configuration>
</execution>
<execution>
<id>os-api-ref-share-v2</id>
<goals>

972
api-ref/source/objectstorage/v1/parameters.yaml
View File

@ -1,972 +0,0 @@
# variables in header
Accept:
description: |
Instead of using the ``format`` query parameter,
set this header to ``application/json``, ``application/xml``, or
``text/xml``.
in: header
required: false
type: string
Accept-Ranges:
description: |
The type of ranges that the object accepts.
in: header
required: true
type: string
Content-Disposition:
description: |
If set, 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.
in: header
required: false
type: string
Content-Disposition_1:
description: |
If set, 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
returned by this operation.
in: header
required: false
type: string
Content-Encoding:
description: |
If set, the value of the ``Content-Encoding``
metadata.
in: header
required: false
type: string
Content-Encoding_1:
description: |
If set, 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:
description: |
If the operation succeeds, this value is zero
(0). If the operation fails, this value is the length of the error
text in the response body.
in: header
required: true
type: string
Content-Length_1:
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.
in: header
required: true
type: string
Content-Length_3:
description: |
HEAD operations do not return content. The
``Content-Length`` header value is not the size of the response
body but is the size of the object, in bytes.
in: header
required: true
type: string
Content-Length_4:
description: |
The length of the object content in the response
body, in bytes.
in: header
required: true
type: string
Content-Type:
description: |
Changes the MIME type for the object.
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:
description: |
The MIME type of the list of names. If the
operation fails, this value is the MIME type of the error text in
the response body.
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.
in: header
required: true
type: string
Destination:
description: |
The container and object name of the destination
object in the form of ``/container/object``. You must UTF-8-encode
and then URL-encode the names of the destination container and
object before you include them in this header.
in: header
required: true
type: string
ETag:
description: |
The MD5 checksum of the copied object content.
The value is not quoted.
in: header
required: true
type: string
ETag_1:
description: |
The MD5 checksum value of the request body. For
example, the MD5 checksum value of the object content. You are
strongly recommended to compute the MD5 checksum value of object
content and include it in the request. This enables the Object
Storage API to check the integrity of the upload. The value is not
quoted.
in: header
required: false
type: string
ETag_2:
description: |
For objects smaller than 5 GB, this value is the
MD5 checksum of the object content. The value is not quoted. For
manifest objects, this value is the MD5 checksum of the
concatenated string of MD5 checksums and ETags for each of the
segments in the manifest, and not the MD5 checksum of the content
that was downloaded. Also the value is enclosed in double-quote
characters. You are strongly recommended to compute the MD5
checksum of the response body as it is received and compare this
value with the one in the ETag header. If they differ, the content
was corrupted, so retry the operation.
in: header
required: true
type: string
If-Match:
description: |
See `Request for Comments: 2616
<http://www.ietf.org/rfc/rfc2616.txt>`_.
in: header
required: false
type: string
If-Modified-Since:
description: |
See `Request for Comments: 2616
<http://www.ietf.org/rfc/rfc2616.txt>`_.
in: header
required: false
type: string
If-None-Match:
description: |
In combination with ``Expect: 100-Continue``,
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
type: string
If-Unmodified-Since:
description: |
See `Request for Comments: 2616
<http://www.ietf.org/rfc/rfc2616.txt>`_.
in: header
required: false
type: string
Last-Modified:
description: |
The date and time when the object was created or its metadata was
changed.
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``.
in: header
required: true
type: string
Range:
description: |
The ranges of content to get. You can use the
``Range`` header to get portions of data by using one or more
range specifications. To specify many ranges, separate the range
specifications with a comma. The types of range specifications
are: - **Byte range specification**. Use FIRST_BYTE_OFFSET to
specify the start of the data range, and LAST_BYTE_OFFSET to
specify the end. You can omit the LAST_BYTE_OFFSET and if you
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 five 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 five
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
Transfer-Encoding:
description: |
Set to ``chunked`` to enable chunked transfer
encoding. If used, do not set the ``Content-Length`` header to a
non-zero value.
in: header
required: false
type: string
X-Account-Bytes-Used:
description: |
The total number of bytes that are stored in
Object Storage for the account.
in: header
required: true
type: integer
X-Account-Container-Count:
description: |
The number of containers.
in: header
required: true
type: integer
X-Account-Meta-Temp-URL-Key:
description: |
The secret key value for temporary URLs. If not
set, this header is not returned in the response.
in: header
required: false
type: string
X-Account-Meta-Temp-URL-Key-2:
description: |
A second secret key value for temporary URLs. If
not set, this header is not returned in the response.
in: header
required: false
type: string
X-Account-Meta-Temp-URL-Key-2_1:
description: |
A second secret key value for temporary URLs. The
second key enables you to rotate keys by having two active keys at
the same time.
in: header
required: false
type: string
X-Account-Meta-Temp-URL-Key_1:
description: |
The secret key value for temporary URLs.
in: header
required: false
type: string
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}``).
in: header
required: false
type: string
X-Account-Meta-name_1:
description: |
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
delete.
in: header
required: false
type: string
X-Account-Object-Count:
description: |
The number of objects in the account.
in: header
required: true
type: integer
X-Auth-Token:
description: |
Authentication token. If you omit this header,
your request fails unless the account owner has granted you access
through an access control list (ACL).
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.
in: header
required: true
type: integer
X-Container-Meta-Access-Control-Allow-Origin:
description: |
Originating URLs allowed to make cross-origin
requests (CORS), separated by spaces. This heading applies to the
container only, and all objects within the container with this
header applied are CORS-enabled for the allowed origin URLs. A
browser (user-agent) typically issues a `preflighted request
<https://developer.mozilla.org/en-
US/docs/HTTP/Access_control_CORS>`_ , which is an OPTIONS call
that verifies the origin is allowed to make the request. The
Object Storage service returns 200 if the originating URL is
listed in this header parameter, and issues a 401 if the
originating URL is not allowed to make a cross-origin request.
Once a 200 is returned, the browser makes a second request to the
Object Storage service to retrieve the CORS-enabled object.
in: header
required: false
type: string
X-Container-Meta-Access-Control-Expose-Headers:
description: |
Headers the Object Storage service exposes to the
browser (technically, through the ``user-agent`` setting), in the
request response, separated by spaces. By default the Object
Storage service returns the following values for this header: -
All “simple response headers” as listed on
`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``.
in: header
required: false
type: string
X-Container-Meta-Access-Control-Max-Age:
description: |
Maximum time for the origin to hold the preflight
results. A browser may make an OPTIONS call to verify the origin
is allowed to make the request. Set the value to an integer number
of seconds after the time that the request was received.
in: header
required: false
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.
in: header
required: false
type: string
X-Container-Meta-Quota-Count:
description: |
Sets maximum object count of the container.
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.
in: header
required: false
type: string
X-Container-Meta-Temp-URL-Key:
description: |
The secret key value for temporary URLs.
in: header
required: false
type: string
X-Container-Meta-Temp-URL-Key-2:
description: |
A second secret key value for temporary URLs. The
second key enables you to rotate keys by having two active keys at
the same time.
in: header
required: false
type: string
X-Container-Meta-Web-Directory-Type:
description: |
Sets the content-type of directory marker
objects. If the header is not set, default is
``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
0-byte objects with a content-type of ``text/directory`` as
directories rather than objects.
in: header
required: false
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
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-Object-Count:
description: |
The number of objects.
in: header
required: true
type: integer
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.
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.
in: header
required: false
type: string
X-Container-Read_1:
description: |
The ACL that grants read access. If not set, this
header is not returned by this operation.
in: header
required: false
type: string
X-Container-Sync-Key:
description: |
Sets the secret key for container
synchronization. If you remove the secret key, synchronization is
halted.
in: header
required: false
type: string
X-Container-Sync-Key_1:
description: |
The secret key for container synchronization. If
not set, this header is not returned by this operation.
in: header
required: false
type: string
X-Container-Sync-To:
description: |
Sets the destination for container
synchronization. Used with the secret key indicated in the ``X
-Container-Sync-Key`` header. If you want to stop a container from
synchronizing, send a blank value for the ``X-Container-Sync-Key``
header.
in: header
required: false
type: string
X-Container-Sync-To_1:
description: |
The destination for container synchronization. If
not set, this header is not returned by this operation.
in: header
required: false
type: string
X-Container-Write:
description: |
Sets an ACL that grants write access.
in: header
required: false
type: string
X-Container-Write_1:
description: |
The ACL that grants write access. If not set,
this header is not returned by this operation.
in: header
required: false
type: string
X-Copied-From:
description: |
For a copied object, shows the container and
object name from which the new object was copied. The value is in
the ``{container}/{object}`` format.
in: header
required: false
type: string
X-Copied-From-Last-Modified:
description: |
For a copied object, the date and time in `UNIX
Epoch time stamp format
<https://en.wikipedia.org/wiki/Unix_time>`_ when the container and
object name from which the new object was copied was last
modified. For example, ``1440619048`` is equivalent to ``Mon,
Wed, 26 Aug 2015 19:57:28 GMT``.
in: header
required: false
type: integer
X-Copy-From:
description: |
If set, this is the name of an object used to
create the new object by copying the ``X-Copy-From`` object. The
value is in form ``{container}/{object}``. You must UTF-8-encode
and then URL-encode the names of the container and object before
you include them in the header. Using PUT with ``X-Copy-From``
has the same effect as using the COPY operation to copy an object.
Using ``Range`` header with ``X-Copy-From`` will create a new
partial copied object with bytes set by ``Range``.
in: header
required: false
type: string
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.
in: header
required: false
type: integer
X-Delete-At:
description: |
The date and time in `UNIX Epoch time stamp
format <https://en.wikipedia.org/wiki/Unix_time>`_ when the system
removes the object. For example, ``1440619048`` is equivalent to
``Mon, Wed, 26 Aug 2015 19:57:28 GMT``.
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.
in: header
required: false
type: boolean
X-Fresh-Metadata:
description: |
Enables object creation that omits existing user
metadata. If set to ``true``, the COPY request creates an object
without existing user metadata. Default value is ``false``.
in: header
required: false
type: boolean
X-Newest:
description: |
If set to true , Object Storage queries all
replicas to return the most recent one. If you omit this header,
Object Storage responds faster after it finds one valid replica.
Because setting this header to true is more expensive for the back
end, use it only when it is absolutely needed.
in: header
required: false
type: boolean
X-Object-Manifest:
description: |
Set to specify that 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``.
You must UTF-8-encode and then URL-encode the names of the
container and prefix before you include them in this header.
in: header
required: false
type: string
X-Object-Manifest_1:
description: |
If set, to 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
required: false
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.
in: header
required: false
type: string
X-Object-Meta-name_1:
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.
in: header
required: true
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.
in: header
required: false
type: string
X-Remove-Versions-Location:
description: |
Set to any value to disable versioning.
in: header
required: false
type: string
X-Static-Large-Object:
description: |
Set to ``true`` if this object is a static large
object manifest object.
in: header
required: true
type: boolean
X-Timestamp:
description: |
The date and time in `UNIX Epoch time stamp
format <https://en.wikipedia.org/wiki/Unix_time>`_ when the
account, container, or object was initially created as a current
version. For example, ``1440619048`` is equivalent to ``Mon, Wed,
26 Aug 2015 19:57:28 GMT``.
in: header
required: true
type: integer
X-Trans-Id:
description: |
A unique transaction ID for this request. Your
service provider might need this value if you report a problem.
in: header
required: true
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
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
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
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
receive responses. The operator can search for the extra
information in the logs.
in: header
required: false
type: string
X-Versions-Location:
description: |
Enables versioning on this container. The value
is the name of another container. You must UTF-8-encode and then
URL-encode the name before you include it in the header. To
disable versioning, set the header to an empty string.
in: header
required: false
type: string
X-Versions-Location_1:
description: |
Enables versioning on this container. The value
is the name of another container. You must UTF-8-encode and then
URL-encode the name before you include it in the header. To
disable versioning, set the header to an empty string.
in: header
required: true
type: string
# variables in path
account:
description: |
The unique name for the account. An account is
also known as the project or tenant.
in: path
required: false
type: string
container:
description: |
The unique 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``.
in: path
required: false
type: string
object:
description: |
The unique name for the object.
in: path
required: false
type: string
# variables in query
delimiter:
description: |
Delimiter value, which returns the object names
that are nested in the container. If you do not set a prefix and
set the delimiter to "/" you may get unexpected results where all
the objects are returned instead of only those with the delimiter
set.
in: query
required: false
type: string
end_marker:
description: |
For a string value, x , returns container names
that are less than the marker value.
in: query
required: false
type: string
filename:
description: |
Overrides the default file name. Object Storage
generates a default file name for GET temporary URLs that is based
on the object name. Object Storage returns this value in the
``Content-Disposition`` response header. Browsers can interpret
this file name value as a file attachment to save. For more
information about temporary URLs, see `Temporary URL middleware
<http://docs.openstack.org/developer/
swift/api/temporary_url_middleware.html>`_.
in: query
required: false
type: string
format:
description: |
The response format. Valid values are ``json``,
``xml``, or ``plain``. The default is ``plain``. If you append
the ``format=xml`` or ``format=json`` query parameter to the
storage account URL, the response shows extended container
information serialized in that format. If you append the
``format=plain`` query parameter, the response lists the container
names separated by newlines.
in: query
required: false
type: string
limit:
description: |
For an integer value n , limits the number of
results to n .
in: query
required: false
type: integer
marker:
description: |
For a string value, x , returns container names
that are greater than the marker value.
in: query
required: false
type: string
multipart-manifest:
description: |
If ``?multipart-manifest=put``, the object is a
static large object manifest and the body contains the manifest.
in: query
required: false
type: string
multipart-manifest_1:
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
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.
in: query
required: false
type: string
multipart-manifest_2:
description: |
If you include the ``multipart-manifest=get``
query parameter and the object is a large object, the object
contents are not returned. Instead, the manifest is returned in
the ``X-Object-Manifest`` response header for dynamic large
objects or in the response body for static large objects.
in: query
required: false
type: string
path:
description: |
For a string value, returns the object names that
are nested in the pseudo path.
in: query
required: false
type: string
prefix:
description: |
Prefix value. Named items in the response begin
with this value.
in: query
required: false
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``.
in: query
required: false
type: integer
swiftinfo_sig:
description: |
A hash-based message authentication code (HMAC)
that enables access to administrator-only information. To use this
parameter, the ``swiftinfo_expires`` parameter is also required.
in: query
required: false
type: string
temp_url_expires:
description: |
The date and time in `UNIX Epoch time stamp
format <https://en.wikipedia.org/wiki/Unix_time>`_ when the
signature for temporary URLs expires. For example, ``1440619048``
is equivalent to ``Mon, Wed, 26 Aug 2015 19:57:28 GMT``. For more
information about temporary URLs, see `Temporary URL middleware
<http://docs.openstack.org/developer/swift/api/temporary
_url_middleware.html>`_.
in: query
required: true
type: integer
temp_url_sig:
description: |
Used with temporary URLs to sign the request with
an HMAC-SHA1 cryptographic signature that defines the allowed HTTP
method, expiration date, full path to the object, and the secret
key for the temporary URL. For more information about temporary
URLs, see `Temporary URL middleware
<http://docs.openstack.org/developer/swif
t/api/temporary_url_middleware.html>`_.
in: query
required: true
type: string
# variables in body
bytes:
description: |
The total number of bytes that are stored in
Object Storage for the account.
in: body
required: true
type: integer
content_type:
description: |
The content type of the object.
in: body
required: true
type: string
count:
description: |
The number of objects in the container.
in: body
required: true
type: integer
hash:
description: |
The MD5 checksum value of the object content.
in: body
required: true
type: string
last_modified:
description: |
The date and time when the object was last modified.
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``.
in: body
required: true
type: string
name:
description: |
The name of the container.
in: body
required: true
type: string

1
api-ref/source/objectstorage/v1/samples/account-containers-list-http-request-json.txt
View File

@ -1 +0,0 @@
curl -i https://23.253.72.207/v1/$account?format=json -X GET -H "X-Auth-Token: $token"

2
api-ref/source/objectstorage/v1/samples/account-containers-list-http-request-xml.txt
View File

@ -1,2 +0,0 @@
curl -i https://23.253.72.207/v1/$account?format=xml \
-X GET -H "X-Auth-Token: $token"

11
api-ref/source/objectstorage/v1/samples/account-containers-list-http-response-json.txt
View File

@ -1,11 +0,0 @@
HTTP/1.1 200 OK
Content-Length: 96
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/json; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
Date: Fri, 17 Jan 2014 15:59:33 GMT

11
api-ref/source/objectstorage/v1/samples/account-containers-list-http-response-xml.txt
View File

@ -1,11 +0,0 @@
HTTP/1.1 200 OK
Content-Length: 262
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/xml; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b
Date: Fri, 17 Jan 2014 16:03:23 GMT

12
api-ref/source/objectstorage/v1/samples/account-containers-list-response.json
View File

@ -1,12 +0,0 @@
[
{
"count": 0,
"bytes": 0,
"name": "janeausten"
},
{
"count": 1,
"bytes": 14,
"name": "marktwain"
}
]

13
api-ref/source/objectstorage/v1/samples/account-containers-list-response.xml
View File

@ -1,13 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<account name="my_account">
<container>
<name>janeausten</name>
<count>0</count>
<bytes>0</bytes>
</container>
<container>
<name>marktwain</name>
<count>1</count>
<bytes>14</bytes>
</container>
</account>

7
api-ref/source/objectstorage/v1/samples/capabilities-list-response.json
View File

@ -1,7 +0,0 @@
{
"swift": {
"version": "1.11.0"
},
"staticweb": {},
"tempurl": {}
}

3
api-ref/source/objectstorage/v1/samples/containers-list-http-request.txt
View File

@ -1,3 +0,0 @@
GET /{api_version}/{account} HTTP/1.1
Host: storage.swiftdrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

9
api-ref/source/objectstorage/v1/samples/containers-list-http-response.txt
View File

@ -1,9 +0,0 @@
HTTP/1.1 200 Ok
Date: Thu, 07 Jun 2010 18:57:07 GMT
Content-Type: text/plain; charset=UTF-8
Content-Length: 32
images
movies
documents
backups

14
api-ref/source/objectstorage/v1/samples/endpoints-list-response-headers.json
View File

@ -1,14 +0,0 @@
{
"endpoints": [
"http://storage01.swiftdrive.com:6008/d8/583/AUTH_dev/EC_cont1/obj",
"http://storage02.swiftdrive.com:6008/d2/583/AUTH_dev/EC_cont1/obj",
"http://storage02.swiftdrive.com:6006/d3/583/AUTH_dev/EC_cont1/obj",
"http://storage02.swiftdrive.com:6008/d5/583/AUTH_dev/EC_cont1/obj",
"http://storage01.swiftdrive.com:6007/d7/583/AUTH_dev/EC_cont1/obj",
"http://storage02.swiftdrive.com:6007/d4/583/AUTH_dev/EC_cont1/obj",
"http://storage01.swiftdrive.com:6006/d6/583/AUTH_dev/EC_cont1/obj"
],
"headers": {
"X-Backend-Storage-Policy-Index": "2"
}
}

8
api-ref/source/objectstorage/v1/samples/endpoints-list-response.json
View File

@ -1,8 +0,0 @@
{
"endpoints": [
"http://storage02.swiftdrive:6002/d2/617/AUTH_dev",
"http://storage01.swiftdrive:6002/d8/617/AUTH_dev",
"http://storage01.swiftdrive:6002/d11/617/AUTH_dev"
],
"headers": {}
}

1
api-ref/source/objectstorage/v1/samples/goodbyeworld.txt
View File

@ -1 +0,0 @@
Goodbye World!

1
api-ref/source/objectstorage/v1/samples/helloworld.txt
View File

@ -1 +0,0 @@
Hello World Again!

10
api-ref/source/objectstorage/v1/samples/objects-list-http-response-json.txt
View File

@ -1,10 +0,0 @@
HTTP/1.1 200 OK
Content-Length: 341
X-Container-Object-Count: 2
Accept-Ranges: bytes
X-Container-Meta-Book: TomSawyer
X-Timestamp: 1389727543.65372
X-Container-Bytes-Used: 26
Content-Type: application/json; charset=utf-8
X-Trans-Id: tx26377fe5fab74869825d1-0052d6bdff
Date: Wed, 15 Jan 2014 16:57:35 GMT

10
api-ref/source/objectstorage/v1/samples/objects-list-http-response-xml.txt
View File

@ -1,10 +0,0 @@
HTTP/1.1 200 OK
Content-Length: 500
X-Container-Object-Count: 2
Accept-Ranges: bytes
X-Container-Meta-Book: TomSawyer
X-Timestamp: 1389727543.65372
X-Container-Bytes-Used: 26
Content-Type: application/xml; charset=utf-8
X-Trans-Id: txc75ea9a6e66f47d79e0c5-0052d6be76
Date: Wed, 15 Jan 2014 16:59:35 GMT

16
api-ref/source/objectstorage/v1/samples/objects-list-response.json
View File

@ -1,16 +0,0 @@
[
{
"hash": "451e372e48e0f6b1114fa0724aa79fa1",
"last_modified": "2014-01-15T16:41:49.390270",
"bytes": 14,
"name": "goodbye",
"content_type": "application/octet-stream"
},
{
"hash": "ed076287532e86365e841e92bfc50d8c",
"last_modified": "2014-01-15T16:37:43.427570",
"bytes": 12,
"name": "helloworld",
"content_type": "application/octet-stream"
}
]

17
api-ref/source/objectstorage/v1/samples/objects-list-response.xml
View File

@ -1,17 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<container name="marktwain">
<object>
<name>goodbye</name>
<hash>451e372e48e0f6b1114fa0724aa79fa1</hash>
<bytes>14</bytes>
<content_type>application/octet-stream</content_type>
<last_modified>2014-01-15T16:41:49.390270</last_modified>
</object>
<object>
<name>helloworld</name>
<hash>ed076287532e86365e841e92bfc50d8c</hash>
<bytes>12</bytes>
<content_type>application/octet-stream</content_type>
<last_modified>2014-01-15T16:37:43.427570</last_modified>
</object>
</container>

380
api-ref/source/objectstorage/v1/storage-account-services.inc
View File

@ -1,380 +0,0 @@
.. -*- rst -*-
========
Accounts
========
Lists containers for an account. Creates, updates, shows, and
deletes account metadata.
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
========================================
.. rest_method:: GET /v1/{account}
Shows details for an account and lists containers, sorted by name, in the account.
The sort order for the name is based on a binary comparison, a
single built-in collating sequence that compares string data by
using the SQLite memcmp() function, regardless of text encoding.
See `Collating Sequences
<http://www.sqlite.org/datatype3.html#collation>`_.
Example requests and responses:
- Show account details and list containers and ask for a JSON
response:
::
curl -i $publicURL?format=json -X GET -H "X-Auth-Token: $token"
- List containers and ask for an XML response:
::
curl -i $publicURL?format=xml -X GET -H "X-Auth-Token: $token"
The response body returns a list of containers. The default
response (``text/plain``) returns one container per line.
If you use query parameters to page through a long list of
containers, you have reached the end of the list if the number of
items in the returned list is less than the request ``limit``
value. The list contains more items if the number of items in the
returned list equals the ``limit`` value.
When asking for a list of containers and there are none, the
response behavior changes depending on whether the request format
is text, JSON, or XML. For a text response, you get a 204 , because
there is no content. However, for a JSON or XML response, you get a
200 with content indicating an empty array.
If the request succeeds, the operation returns one of these status
codes:
- ``OK (200)``. Success. The response body lists the containers.
- ``No Content (204)``. Success. The response body shows no
containers. Either the account has no containers or you are
paging through a long list of names by using the ``marker``,
``limit``, or ``end_marker`` query parameter and you have reached
the end of the list.
Normal response codes: 200
Error response codes:204,
Request
-------
.. rest_parameters:: parameters.yaml
- account: account
- limit: limit
- marker: marker
- end_marker: end_marker
- format: format
- prefix: prefix
- delimiter: delimiter
- X-Auth-Token: X-Auth-Token
- X-Newest: X-Newest
- Accept: Accept
- X-Trans-Id-Extra: X-Trans-Id-Extra
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Content-Length: Content-Length
- X-Account-Meta-name: X-Account-Meta-name
- X-Account-Object-Count: X-Account-Object-Count
- 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
- count: count
- bytes: bytes
- name: name
Response Example
----------------
.. literalinclude:: samples/account-containers-list-http-response-xml.txt
:language: javascript
Create, update, or delete account metadata
==========================================
.. rest_method:: POST /v1/{account}
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
metadata item.
Subsequent requests for the same key and value pair overwrite the
existing value.
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
value.
If the container already has other custom metadata items, a request
to create, update, or delete metadata does not affect those items.
This operation does not accept a request body.
Example requests and responses:
- Create account metadata:
::
curl -i $publicURL -X POST -H "X-Auth-Token: $token" -H "X-Account-Meta-Book: MobyDick" -H "X-Account-Meta-Subject: Literature"
::
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx8c2dd6aee35442a4a5646-0052d954fb
Date: Fri, 17 Jan 2014 16:06:19 GMT
- Update account metadata:
::
curl -i $publicURL -X POST -H "X-Auth-Token: $token" -H "X-Account-Meta-Subject: AmericanLiterature"
::
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx1439b96137364ab581156-0052d95532
Date: Fri, 17 Jan 2014 16:07:14 GMT
- Delete account metadata:
::
curl -i $publicURL -X POST -H "X-Auth-Token: $token" -H "X-Remove-Account-Meta-Subject: x"
::
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx411cf57701424da99948a-0052d9556f
Date: Fri, 17 Jan 2014 16:08:15 GMT
If the request succeeds, the operation returns the ``No Content
(204)`` response code.
To confirm your changes, issue a show account metadata request.
Error response codes:204,
Request
-------
.. rest_parameters:: parameters.yaml
- account: account
- X-Auth-Token: X-Auth-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-Trans-Id-Extra: X-Trans-Id-Extra
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Date: Date
- X-Timestamp: X-Timestamp
- Content-Length: Content-Length
- Content-Type: Content-Type
- X-Trans-Id: X-Trans-Id
Show account metadata
=====================
.. rest_method:: HEAD /v1/{account}
Shows metadata for an account.
Metadata for the account includes:
- Number of containers
- Number of objects
- Total number of bytes that are stored in Object Storage for the
account
Because the storage system can store large amounts of data, take
care when you represent the total bytes response as an integer;
when possible, convert it to a 64-bit unsigned integer if your
platform supports that primitive type.
Do not include metadata headers in this request.
Show account metadata request:
::
curl -i $publicURL -X HEAD -H "X-Auth-Token: $token"
::
HTTP/1.1 204 No Content
Content-Length: 0
X-Account-Object-Count: 1
X-Account-Meta-Book: MobyDick
X-Timestamp: 1389453423.35964
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: text/plain; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: txafb3504870144b8ca40f7-0052d955d4
Date: Fri, 17 Jan 2014 16:09:56 GMT
If the account or authentication token is not valid, the operation
returns the ``Unauthorized (401)`` response code.
Error response codes:204,401,
Request
-------
.. rest_parameters:: parameters.yaml
- account: account
- X-Auth-Token: X-Auth-Token
- X-Newest: X-Newest
- X-Trans-Id-Extra: X-Trans-Id-Extra
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Content-Length: Content-Length
- X-Account-Meta-name: X-Account-Meta-name
- X-Account-Object-Count: X-Account-Object-Count
- 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

503
api-ref/source/objectstorage/v1/storage-container-services.inc
View File

@ -1,503 +0,0 @@
.. -*- rst -*-
==========
Containers
==========
Lists objects in a container. Creates, shows details for, and
deletes containers. Creates, updates, shows, and deletes container
metadata.
Show container details and list objects
=======================================
.. rest_method:: GET /v1/{account}/{container}
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,
up to 10,000 names. The 10,000 maximum value is configurable. To
view the value for the cluster, issue a GET ``/info`` request.
Example requests and responses:
- ``OK (200)``. Success. The response body lists the objects.
- ``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
``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,
Request
-------
.. rest_parameters:: parameters.yaml
- account: account
- container: container
- limit: limit
- marker: marker
- end_marker: end_marker
- prefix: prefix
- format: format
- delimiter: delimiter
- path: path
- X-Auth-Token: X-Auth-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
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- X-Container-Meta-name: X-Container-Meta-name
- Content-Length: Content-Length
- X-Container-Object-Count: X-Container-Object-Count
- 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-Timestamp: X-Timestamp
- X-Trans-Id: X-Trans-Id
- Date: Date
- Content-Type: Content-Type
- hash: hash
- last_modified: last_modified
- bytes: bytes
- name: name
- content_type: content_type
Response Example
----------------
.. literalinclude:: samples/objects-list-http-response-xml.txt
:language: javascript
Create container
================
.. rest_method:: PUT /v1/{account}/{container}
Creates a container.
You do not need to check whether a container already exists before
issuing a PUT operation because the operation is idempotent: It
creates a container or updates an existing container, as
appropriate.
Example requests and responses:
- Create a container with no metadata:
::
curl -i $publicURL/steven -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"
::
HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx7f6b7fa09bc2443a94df0-0052d58b56
Date: Tue, 14 Jan 2014 19:09:10 GMT
- Create a container with metadata:
::
curl -i $publicURL/marktwain -X PUT -H "X-Auth-Token: $token" -H "X-Container-Meta-Book: TomSawyer"
::
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
Error response codes:201,204,
Request
-------
.. rest_parameters:: parameters.yaml
- account: account
- container: container
- X-Auth-Token: X-Auth-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-Container-Meta-name: X-Container-Meta-name
- 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
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Date: Date
- X-Timestamp: X-Timestamp
- Content-Length: Content-Length
- Content-Type: Content-Type
- X-Trans-Id: X-Trans-Id
Create, update, or delete container metadata
============================================
.. rest_method:: POST /v1/{account}/{container}
Creates, updates, or deletes custom metadata for a container.
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.
Subsequent requests for the same key and value pair overwrite the
previous value.
To delete container metadata, send an empty value for that header,
such as for the ``X-Container-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-
Container-Meta-{name}`` header with an arbitrary value. For
example, ``X-Remove-Container-Meta-Book: x``. The operation ignores
the arbitrary value.
If the container already has other custom metadata items, a request
to create, update, or delete metadata does not affect those items.
Example requests and responses:
- Create container metadata:
::
curl -i $publicURL/marktwain -X POST -H "X-Auth-Token: $token" -H "X-Container-Meta-Author: MarkTwain" -H "X-Container-Meta-Web-Directory-Type: text/directory" -H "X-Container-Meta-Century: Nineteenth"
::
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx05dbd434c651429193139-0052d82635
Date: Thu, 16 Jan 2014 18:34:29 GMT
- Update container metadata:
::
curl -i $publicURL/marktwain -X POST -H "X-Auth-Token: $token" -H "X-Container-Meta-Author: SamuelClemens"
::
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txe60c7314bf614bb39dfe4-0052d82653
Date: Thu, 16 Jan 2014 18:34:59 GMT
- Delete container metadata:
::
curl -i $publicURL/marktwain -X POST -H "X-Auth-Token: $token" -H "X-Remove-Container-Meta-Century: x"
::
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx7997e18da2a34a9e84ceb-0052d826d0
Date: Thu, 16 Jan 2014 18:37:04 GMT
If the request succeeds, the operation returns the ``No Content
(204)`` response code.
To confirm your changes, issue a show container metadata request.
Error response codes:204,
Request
-------
.. rest_parameters:: parameters.yaml
- account: account
- container: container
- X-Auth-Token: X-Auth-Token
- X-Container-Read: X-Container-Read
- X-Remove-Container-name: X-Remove-Container-name
- 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-Remove-Versions-Location: X-Remove-Versions-Location
- X-Container-Meta-name: X-Container-Meta-name
- 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
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Date: Date
- X-Timestamp: X-Timestamp
- Content-Length: Content-Length
- Content-Type: Content-Type
- X-Trans-Id: X-Trans-Id
Show container metadata
=======================
.. rest_method:: HEAD /v1/{account}/{container}
Shows container metadata, including the number of objects and the total bytes of all objects stored in the container.
Show container metadata request:
::
curl -i $publicURL/marktwain -X HEAD -H "X-Auth-Token: $token"
::
HTTP/1.1 204 No Content
Content-Length: 0
X-Container-Object-Count: 1
Accept-Ranges: bytes
X-Container-Meta-Book: TomSawyer
X-Timestamp: 1389727543.65372
X-Container-Meta-Author: SamuelClemens
X-Container-Bytes-Used: 14
Content-Type: text/plain; charset=utf-8
X-Trans-Id: tx0287b982a268461b9ec14-0052d826e2
Date: Thu, 16 Jan 2014 18:37:22 GMT
If the request succeeds, the operation returns the ``No Content
(204)`` response code.
Error response codes:204,
Request
-------
.. rest_parameters:: parameters.yaml
- account: account
- container: container
- X-Auth-Token: X-Auth-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
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
- X-Container-Object-Count: X-Container-Object-Count
- X-Container-Write: X-Container-Write
- X-Container-Meta-Quota-Count: X-Container-Meta-Quota-Count
- Accept-Ranges: Accept-Ranges
- X-Container-Read: X-Container-Read
- 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
- 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
Delete container
================
.. rest_method:: DELETE /v1/{account}/{container}
Deletes an empty container.
This operation fails unless the container is empty. An empty
container has no objects.
Delete the ``steven`` container:
::
curl -i $publicURL/steven -X DELETE -H "X-Auth-Token: $token"
If the container does not exist, the response is:
::
HTTP/1.1 404 Not Found
Content-Length: 70
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx4d728126b17b43b598bf7-0052d81e34
Date: Thu, 16 Jan 2014 18:00:20 GMT
If the container exists and the deletion succeeds, the response is:
::
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txf76c375ebece4df19c84c-0052d81f14
Date: Thu, 16 Jan 2014 18:04:04 GMT
If the container exists but is not empty, the response is:
::
HTTP/1.1 409 Conflict
Content-Length: 95
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx7782dc6a97b94a46956b5-0052d81f6b
Date: Thu, 16 Jan 2014 18:05:31 GMT
<html>
<h1>Conflict
</h1>
<p>There was a conflict when trying to complete your request.
</p>
</html>
Error response codes:404,204,409,
Request
-------
.. rest_parameters:: parameters.yaml
- 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-Trans-Id-Extra: X-Trans-Id-Extra
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Date: Date
- X-Timestamp: X-Timestamp
- Content-Length: Content-Length
- Content-Type: Content-Type
- X-Trans-Id: X-Trans-Id

695
api-ref/source/objectstorage/v1/storage-object-services.inc
View File

@ -1,695 +0,0 @@
.. -*- rst -*-
=======
Objects
=======
Creates, replaces, shows details for, and deletes objects. Copies
objects from another object with a new or different name. Updates
object metadata.
Get object content and metadata
===============================
.. rest_method:: GET /v1/{account}/{container}/{object}
Downloads the object content and gets the object metadata.
This operation returns the object metadata in the response headers
and the object content in the response body.
If this is a large object, the response body contains the
concatenated content of the segment objects. To get the manifest
instead of concatenated segment objects for a static large object,
use the ``multipart-manifest`` query parameter.
Example requests and responses:
- Show object details for the ``goodbye`` object in the
``marktwain`` container:
::
curl -i $publicURL/marktwain/goodbye -X GET -H "X-Auth-Token: $token"
::
HTTP/1.1 200 OK
Content-Length: 14
Accept-Ranges: bytes
Last-Modified: Wed, 15 Jan 2014 16:41:49 GMT
Etag: 451e372e48e0f6b1114fa0724aa79fa1
X-Timestamp: 1389804109.39027
X-Object-Meta-Orig-Filename: goodbyeworld.txt
Content-Type: application/octet-stream
X-Trans-Id: tx8145a190241f4cf6b05f5-0052d82a34
Date: Thu, 16 Jan 2014 18:51:32 GMT
Goodbye World!
- Show object details for the ``goodbye`` object, which does not
exist, in the ``janeausten`` container:
::
curl -i $publicURL/janeausten/goodbye -X GET -H "X-Auth-Token: $token"
::
HTTP/1.1 404 Not Found
Content-Length: 70
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx073f7cbb850c4c99934b9-0052d82b04
Date: Thu, 16 Jan 2014 18:55:00 GMT
<html>
<h1>Not Found
</h1>
<p>The resource could not be found.
</p>
</html>
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,
Request
-------
.. rest_parameters:: parameters.yaml
- account: account
- object: object
- container: container
- X-Auth-Token: X-Auth-Token
- X-Newest: X-Newest
- temp_url_sig: temp_url_sig
- temp_url_expires: temp_url_expires
- filename: filename
- multipart-manifest: multipart-manifest
- Range: Range
- If-Match: If-Match
- If-None-Match: If-None-Match
- If-Modified-Since: If-Modified-Since
- If-Unmodified-Since: If-Unmodified-Since
- X-Trans-Id-Extra: X-Trans-Id-Extra
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
- X-Delete-At: X-Delete-At
- Accept-Ranges: Accept-Ranges
- X-Object-Manifest: X-Object-Manifest
- Last-Modified: Last-Modified
- ETag: ETag
- X-Timestamp: X-Timestamp
- X-Trans-Id: X-Trans-Id
- Date: Date
- X-Static-Large-Object: X-Static-Large-Object
- Content-Type: Content-Type
Response Example
----------------
.. literalinclude::
:language: javascript
Create or replace object
========================
.. rest_method:: PUT /v1/{account}/{container}/{object}
Creates an object with data content and metadata, or replaces an existing object with data content and metadata.
The PUT 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
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.
Example requests and responses:
- Create object:
::
curl -i $publicURL/janeausten/helloworld.txt -X PUT -H "Content-Length: 1" -H "Content-Type: text/html; charset=UTF-8" -H "X-Auth-Token: $token"
::
HTTP/1.1 201 Created
Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT
Content-Length: 116
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
Date: Fri, 17 Jan 2014 17:28:35 GMT
- Replace object:
::
curl -i $publicURL/janeausten/helloworld -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token"
::
HTTP/1.1 201 Created
Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT
Content-Length: 116
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843
Date: Fri, 17 Jan 2014 17:28:35 GMT
The ``Created (201)`` response code indicates a successful write.
If the request times out, the operation returns the ``Request
Timeout (408)`` response code.
The ``Length Required (411)`` response code indicates a missing
``Transfer-Encoding`` or ``Content-Length`` request header.
If the MD5 checksum of the data that is written to the object store
does not match the optional ``ETag`` value, the operation returns
the ``Unprocessable Entity (422)`` response code.
Error response codes:201,422,411,408,
Request
-------
.. rest_parameters:: parameters.yaml
- account: account
- object: object
- container: container
- multipart-manifest: multipart-manifest
- 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
- Transfer-Encoding: Transfer-Encoding
- Content-Type: Content-Type
- X-Detect-Content-Type: X-Detect-Content-Type
- X-Copy-From: X-Copy-From
- ETag: ETag
- Content-Disposition: Content-Disposition
- Content-Encoding: Content-Encoding
- X-Delete-At: X-Delete-At
- X-Delete-After: X-Delete-After
- X-Object-Meta-name: X-Object-Meta-name
- If-None-Match: If-None-Match
- X-Trans-Id-Extra: X-Trans-Id-Extra
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Content-Length: Content-Length
- ETag: ETag
- X-Timestamp: X-Timestamp
- X-Trans-Id: X-Trans-Id
- Date: Date
- Content-Type: Content-Type
- last_modified: last_modified
Copy object
===========
.. rest_method:: COPY /v1/{account}/{container}/{object}
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.
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
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
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
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.
Example requests and responses:
- Copy the ``goodbye`` object from the ``marktwain`` container to
the ``janeausten`` container:
::
curl -i $publicURL/marktwain/goodbye -X COPY -H "X-Auth-Token: $token" -H "Destination: janeausten/goodbye"
::
HTTP/1.1 201 Created
Content-Length: 0
X-Copied-From-Last-Modified: Thu, 16 Jan 2014 21:19:45 GMT
X-Copied-From: marktwain/goodbye
Last-Modified: Fri, 17 Jan 2014 18:22:57 GMT
Etag: 451e372e48e0f6b1114fa0724aa79fa1
Content-Type: text/html; charset=UTF-8
X-Object-Meta-Movie: AmericanPie
X-Trans-Id: txdcb481ad49d24e9a81107-0052d97501
Date: Fri, 17 Jan 2014 18:22:57 GMT
- Alternatively, you can use PUT to copy the ``goodbye`` object from
the ``marktwain`` container to the ``janeausten`` container. This
request requires a ``Content-Length`` header, even if it is set
to zero (0).
::
curl -i $publicURL/janeausten/goodbye -X PUT -H "X-Auth-Token: $token" -H "X-Copy-From: /marktwain/goodbye" -H "Content-Length: 0"
::
HTTP/1.1 201 Created
Content-Length: 0
X-Copied-From-Last-Modified: Thu, 16 Jan 2014 21:19:45 GMT
X-Copied-From: marktwain/goodbye
Last-Modified: Fri, 17 Jan 2014 18:22:57 GMT
Etag: 451e372e48e0f6b1114fa0724aa79fa1
Content-Type: text/html; charset=UTF-8
X-Object-Meta-Movie: AmericanPie
X-Trans-Id: txdcb481ad49d24e9a81107-0052d97501
Date: Fri, 17 Jan 2014 18:22:57 GMT
When several replicas exist, the system copies from the most recent
replica. That is, the COPY operation behaves as though the
``X-Newest`` header is in the request.
Error response codes:201,
Request
-------
.. rest_parameters:: parameters.yaml
- account: account
- object: object
- container: container
- X-Auth-Token: X-Auth-Token
- Destination: Destination
- Content-Type: Content-Type
- Content-Encoding: Content-Encoding
- Content-Disposition: Content-Disposition
- X-Object-Meta-name: X-Object-Meta-name
- X-Fresh-Metadata: X-Fresh-Metadata
- X-Trans-Id-Extra: X-Trans-Id-Extra
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Content-Length: Content-Length
- X-Object-Meta-name: X-Object-Meta-name
- X-Copied-From-Last-Modified: X-Copied-From-Last-Modified
- X-Copied-From: X-Copied-From
- Last-Modified: Last-Modified
- ETag: ETag
- X-Timestamp: X-Timestamp
- X-Trans-Id: X-Trans-Id
- Date: Date
- Content-Type: Content-Type
Delete object
=============
.. rest_method:: DELETE /v1/{account}/{container}/{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``
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
deletes the manifest object.
Example request and response:
- Delete the ``helloworld`` object from the ``marktwain`` container:
::
curl -i $publicURL/marktwain/helloworld -X DELETE -H "X-Auth-Token: $token"
::
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx36c7606fcd1843f59167c-0052d6fdac
Date: Wed, 15 Jan 2014 21:29:16 GMT
Typically, the DELETE operation does not return a response body.
However, with the ``multipart-manifest=delete`` query parameter,
the response body contains a list of manifest and segment objects
and the status of their DELETE operations.
Error response codes:204,
Request
-------
.. rest_parameters:: parameters.yaml
- account: account
- object: object
- container: container
- multipart-manifest: multipart-manifest
- X-Auth-Token: X-Auth-Token
- X-Trans-Id-Extra: X-Trans-Id-Extra
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Date: Date
- X-Timestamp: X-Timestamp
- Content-Length: Content-Length
- Content-Type: Content-Type
- X-Trans-Id: X-Trans-Id
Show object metadata
====================
.. rest_method:: HEAD /v1/{account}/{container}/{object}
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:
- Show object metadata:
::
curl -i $publicURL/marktwain/goodbye -X HEAD -H "X-Auth-Token: $token"
::
HTTP/1.1 200 OK
Content-Length: 14
Accept-Ranges: bytes
Last-Modified: Thu, 16 Jan 2014 21:12:31 GMT
Etag: 451e372e48e0f6b1114fa0724aa79fa1
X-Timestamp: 1389906751.73463
X-Object-Meta-Book: GoodbyeColumbus
Content-Type: application/octet-stream
X-Trans-Id: tx37ea34dcd1ed48ca9bc7d-0052d84b6f
Date: Thu, 16 Jan 2014 21:13:19 GMT
If the request succeeds, the operation returns the ``200`` response
code.
Normal response codes: 200
Error response codes:204,
Request
-------
.. rest_parameters:: parameters.yaml
- account: account
- object: object
- container: container
- X-Auth-Token: X-Auth-Token
- temp_url_sig: temp_url_sig
- temp_url_expires: temp_url_expires
- filename: filename
- X-Newest: X-Newest
- X-Trans-Id-Extra: X-Trans-Id-Extra
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Last-Modified: Last-Modified
- Content-Length: Content-Length
- X-Object-Meta-name: X-Object-Meta-name
- Content-Disposition: Content-Disposition
- Content-Encoding: Content-Encoding
- X-Delete-At: X-Delete-At
- X-Object-Manifest: X-Object-Manifest
- Last-Modified: Last-Modified
- ETag: ETag
- X-Timestamp: X-Timestamp
- X-Trans-Id: X-Trans-Id
- Date: Date
- X-Static-Large-Object: X-Static-Large-Object
- Content-Type: Content-Type
Response Example
----------------
.. literalinclude::
:language: javascript
Create or update object metadata
================================
.. rest_method:: POST /v1/{account}/{container}/{object}
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
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
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)
object.
A POST request deletes any existing custom metadata that you added
with a previous PUT or POST request. Consequently, you must specify
all custom metadata in the request. However, system metadata is
unchanged by the POST request unless you explicitly supply it in a
request header.
You can also set the ``X-Delete-At`` or ``X-Delete-After`` header
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.
You can also use the `form POST feature
<http://docs.openstack.org/liberty/config-reference/content/object-
storage-form-post.html>`_ to upload objects.
Example requests and responses:
- Create object metadata:
::
curl -i $publicURL/marktwain/goodbye -X POST -H "X-Auth-Token: $token" -H "X-Object-Meta-Book: GoodbyeColumbus"
::
HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txb5fb5c91ba1f4f37bb648-0052d84b3f
Date: Thu, 16 Jan 2014 21:12:31 GMT
<html>
<h1>Accepted
</h1>
<p>The request is accepted for processing.
</p>
</html>
- Update object metadata:
::
curl -i $publicURL/marktwain/goodbye -X POST -H "X-Auth-Token: $token" H "X-Object-Meta-Book: GoodbyeOldFriend"
::
HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx5ec7ab81cdb34ced887c8-0052d84ca4
Date: Thu, 16 Jan 2014 21:18:28 GMT
<html>
<h1>Accepted
</h1>
<p>The request is accepted for processing.
</p>
</html>
Error response codes:202,
Request
-------
.. rest_parameters:: parameters.yaml
- account: account
- object: object
- container: container
- X-Auth-Token: X-Auth-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
- X-Trans-Id-Extra: X-Trans-Id-Extra
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Date: Date
- X-Timestamp: X-Timestamp
- Content-Length: Content-Length
- Content-Type: Content-Type
- X-Trans-Id: X-Trans-Id

38
api-ref/source/objectstorage/v1/storage_endpoints.inc
View File

@ -1,38 +0,0 @@
.. -*- rst -*-
=========
Endpoints
=========
If configured, lists endpoints for an account.
List endpoints
==============
.. rest_method:: GET /v1/endpoints
Lists endpoints for an object, account, or container.
When the cloud provider enables middleware to list the
``/endpoints/`` path, software that needs data location information
can use this call to avoid network overhead. The cloud provider can
map the ``/endpoints/`` path to another resource, so this exact
resource might vary from provider to provider. Because it goes
straight to the middleware, the call is not authenticated, so be
sure you have tightly secured the environment and network when
using this call.
Error response codes:201,
Request
-------
.. rest_parameters:: parameters.yaml

41
api-ref/source/objectstorage/v1/storage_info.inc
View File

@ -1,41 +0,0 @@
.. -*- rst -*-
===============
Discoverability
===============
If configured, lists the activated capabilities for this version of
the OpenStack Object Storage API.
List activated capabilities
===========================
.. rest_method:: GET /info
Lists the activated capabilities for this version of the OpenStack Object Storage API.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- swiftinfo_sig: swiftinfo_sig
- swiftinfo_expires: swiftinfo_expires
Response Example
----------------
.. literalinclude:: samples/capabilities-list-response.json
:language: javascript

23
api-ref/src/docbkx/api-ref-objectstorage-v1.xml
View File

@ -1,23 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:linkend="http://www.w3.org/1999/linkend"
xmlns:xref="http://www.w3.org/1999/xref"
xmlns:wadl="http://wadl.dev.java.net/2009/02"
version="5.0-extension RackBook-2.0"
xml:id="api.openstack.org-objectstorage-v1" status="SUPPORTED">
<info xreflabel="api-ref-objectstorage-v1.html">
<title>OpenStack Object Storage API v1 (SUPPORTED)</title>
<copyright>
<year>2010-2016</year>
</copyright>
<legalnotice role="apache2">
<para/>
</legalnotice>
<annotation>
<xi:include href="itemizedlist-service-list.xml"/>
</annotation>
</info>
<xi:include href="ch_objectstorage-v1.xml"/>
</book>

283
api-ref/src/docbkx/ch_objectstorage-v1.xml
View File

@ -1,283 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
<!ENTITY % common_project SYSTEM "../wadls/common_project.ent">
%common_project;
]>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:linkend="http://www.w3.org/1999/linkend"
xmlns:xref="http://www.w3.org/1999/xref"
xmlns:wadl="http://wadl.dev.java.net/2009/02"
version="5.0-extension RackBook-2.0" xml:id="objectstorage-v1"
role="api-reference">
<title>Object Storage API v1 (SUPPORTED)</title>
<para>
Manages the accounts, containers, and objects in the Object Storage
system.
</para>
<para>
To run the cURL command examples for these requests, set these
environment variables:
</para>
<itemizedlist>
<listitem>
<para>
<code>publicURL</code>. The public URL that is the HTTP
endpoint from where you can access Object Storage. It includes
the Object Storage API version number and your account name.
For example, <code>https://23.253.72.207/v1/my_account</code>.
</para>
</listitem>
<listitem>
<para>
<code>token</code>. The authentication token for
Object Storage.
</para>
</listitem>
</itemizedlist>
<para>
To obtain these values, run the <command>swift stat -v</command>
command.
</para>
<para>
As shown in this example, the public URL appears in the
<code>StorageURL</code> field, and the token appears in the <code>Auth
Token</code> field:
</para>
<programlisting>StorageURL: https://23.253.72.207/v1/my_account
Auth Token: {token}
Account: my_account
Containers: 2
Objects: 3
Bytes: 47
Meta Book: MobyDick
X-Timestamp: 1389453423.35964
X-Trans-Id: txee55498935404a2caad89-0052dd3b77
Content-Type: text/plain; charset=utf-8
Accept-Ranges: bytes</programlisting>
<para>
For a complete description of HTTP 1.1 header definitions, see <link
xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14">Header
Field Definitions</link>.
</para>
<para>
The API returns the <code>Range Not Satisfiable (416)</code> response
code for any ranged &GET; requests that specify more than:
</para>
<itemizedlist>
<listitem>
<para>
Fifty ranges.
</para>
</listitem>
<listitem>
<para>
Three overlapping ranges.
</para>
</listitem>
<listitem>
<para>
Eight non-increasing ranges.
</para>
</listitem>
</itemizedlist>
<section xml:id="storage_info">
<title>Discoverability</title>
<para>
If configured, lists the activated capabilities for this version
of the OpenStack Object Storage API.
</para>
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
<wadl:resource href="../wadls/object-api/src/os-object-api-1.0.wadl#info">
<wadl:method href="#infoDiscoverability"/>
</wadl:resource>
</wadl:resources>
</section>
<section xml:id="storage_endpoints">
<title>Endpoints</title>
<para>
If configured, lists endpoints for an account.
</para>
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
<wadl:resource
href="../wadls/object-api/src/os-object-api-1.0.wadl#endpoints">
<wadl:method href="#listEndpoints"/>
</wadl:resource>
</wadl:resources>
</section>
<section xml:id="storage_account_services">
<title>Accounts</title>
<para>
Lists containers for an account. Creates, updates, shows,
and deletes account metadata.
</para>
<para>
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:
</para>
<table rules="all" frame="border">
<caption>Account metadata operations</caption>
<col width="45%"/>
<col width="55%"/>
<thead>
<tr>
<th>POST request body contains</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<para>
A metadata key without a value.
</para>
<para>
The metadata key already exists for the account.
</para>
</td>
<td>
<para>
The API removes the metadata item from the
account.
</para>
</td>
</tr>
<tr>
<td>
<para>
A metadata key without a value.
</para>
<para>
The metadata key does not already exist for the
account.
</para>
</td>
<td>
<para>
The API ignores the metadata key.
</para>
</td>
</tr>
<tr>
<td>
<para>
A metadata key value.
</para>
<para>
The metadata key already exists for the account.
</para>
</td>
<td>
<para>
The API updates the metadata key value for the account.
</para>
</td>
</tr>
<tr>
<td>
<para>
A metadata key value.
</para>
<para>
The metadata key does not already exist for the
account.
</para>
</td>
<td>
<para>
The API adds the metadata key and value pair, or
item, to the account.
</para>
</td>
</tr>
<tr>
<td>
<para>
One or more account metadata items are omitted.
</para>
<para>
The
metadata items already exist for the account.
</para>
</td>
<td>
<para>
The API does not change the existing metadata items.
</para>
</td>
</tr>
</tbody>
</table>
<para></para>
<para>
For these requests, specifying the <code>X-Remove-Account-Meta-*</code> request header
for the key with any value is equivalent to specifying the <code>X-Account-Meta-*</code>
request header with an empty value.
</para>
<para>
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 <link
xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616.html">HTTP/1.1</link>. Also,
Object Storage does not support the underscore character, which it silently converts to
a hyphen.
</para>
<para>
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 <link
xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2">basic
rules</link>.
</para>
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
<wadl:resource
href="../wadls/object-api/src/os-object-api-1.0.wadl#account">
<wadl:method href="#showAccountDetails"/>
<wadl:method href="#updateAccountMeta"/>
<wadl:method href="#showAccountMeta"/>
</wadl:resource>
</wadl:resources>
</section>
<section xml:id="storage_container_services">
<title>Containers</title>
<para>
Lists objects in a container. Creates, shows details
for, and deletes containers. Creates, updates, shows, and deletes
container metadata.
</para>
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
<wadl:resource
href="../wadls/object-api/src/os-object-api-1.0.wadl#container">
<wadl:method href="#showContainerDetails"/>
<wadl:method href="#createContainer"/>
<wadl:method href="#deleteContainer"/>
<wadl:method href="#updateContainerMeta"/>
<wadl:method href="#showContainerMeta"/>
</wadl:resource>
</wadl:resources>
</section>
<section xml:id="storage_object_services">
<title>Objects</title>
<para>
Creates, replaces, shows details for, and deletes objects. Copies
objects from another object with a new or different name. Updates
object metadata.
</para>
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
<wadl:resource
href="../wadls/object-api/src/os-object-api-1.0.wadl#object">
<wadl:method href="#showObject"/>
<wadl:method href="#createOrReplaceObject"/>
<wadl:method href="#copyObject"/>
<wadl:method href="#deleteObject"/>
<wadl:method href="#showObjectMeta"/>
<wadl:method href="#updateObjectMeta"/>
</wadl:resource>
</wadl:resources>
</section>
</chapter>

2
api-ref/src/docbkx/itemizedlist-service-list.xml
View File

@ -87,7 +87,7 @@
</listitem>
<listitem>
<para>
<link xlink:type="simple" xlink:href="api-ref-objectstorage-v1.html">Object Storage API v1 (SUPPORTED)</link>
<link xlink:type="simple" xlink:href="api-ref/object-storage/index.html">Object Storage API v1 (SUPPORTED)</link>
</para>
</listitem>
<listitem>

1564
api-ref/src/wadls/object-api/src/common.ent
View File

File diff suppressed because it is too large Load Diff

1460
api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl
View File

File diff suppressed because it is too large Load Diff

1
api-ref/src/wadls/object-api/src/samples/account-containers-list-http-request-json.txt
View File

@ -1 +0,0 @@
curl -i https://23.253.72.207/v1/$account?format=json -X GET -H "X-Auth-Token: $token"

2
api-ref/src/wadls/object-api/src/samples/account-containers-list-http-request-xml.txt
View File

@ -1,2 +0,0 @@
curl -i https://23.253.72.207/v1/$account?format=xml \
-X GET -H "X-Auth-Token: $token"

11
api-ref/src/wadls/object-api/src/samples/account-containers-list-http-response-json.txt
View File

@ -1,11 +0,0 @@
HTTP/1.1 200 OK
Content-Length: 96
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/json; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
Date: Fri, 17 Jan 2014 15:59:33 GMT

11
api-ref/src/wadls/object-api/src/samples/account-containers-list-http-response-xml.txt
View File

@ -1,11 +0,0 @@
HTTP/1.1 200 OK
Content-Length: 262
X-Account-Object-Count: 1
X-Timestamp: 1389453423.35964
X-Account-Meta-Subject: Literature
X-Account-Bytes-Used: 14
X-Account-Container-Count: 2
Content-Type: application/xml; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b
Date: Fri, 17 Jan 2014 16:03:23 GMT

12
api-ref/src/wadls/object-api/src/samples/account-containers-list-response.json
View File

@ -1,12 +0,0 @@
[
{
"count": 0,
"bytes": 0,
"name": "janeausten"
},
{
"count": 1,
"bytes": 14,
"name": "marktwain"
}
]

13
api-ref/src/wadls/object-api/src/samples/account-containers-list-response.xml
View File

@ -1,13 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<account name="my_account">
<container>
<name>janeausten</name>
<count>0</count>
<bytes>0</bytes>
</container>
<container>
<name>marktwain</name>
<count>1</count>
<bytes>14</bytes>
</container>
</account>

7
api-ref/src/wadls/object-api/src/samples/capabilities-list-response.json
View File

@ -1,7 +0,0 @@
{
"swift": {
"version": "1.11.0"
},
"staticweb": {},
"tempurl": {}
}

3
api-ref/src/wadls/object-api/src/samples/containers-list-http-request.txt
View File

@ -1,3 +0,0 @@
GET /{api_version}/{account} HTTP/1.1
Host: storage.swiftdrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

9
api-ref/src/wadls/object-api/src/samples/containers-list-http-response.txt
View File

@ -1,9 +0,0 @@
HTTP/1.1 200 Ok
Date: Thu, 07 Jun 2010 18:57:07 GMT
Content-Type: text/plain; charset=UTF-8
Content-Length: 32
images
movies
documents
backups

14
api-ref/src/wadls/object-api/src/samples/endpoints-list-response-headers.json
View File

@ -1,14 +0,0 @@
{
"endpoints": [
"http://storage01.swiftdrive.com:6008/d8/583/AUTH_dev/EC_cont1/obj",
"http://storage02.swiftdrive.com:6008/d2/583/AUTH_dev/EC_cont1/obj",
"http://storage02.swiftdrive.com:6006/d3/583/AUTH_dev/EC_cont1/obj",
"http://storage02.swiftdrive.com:6008/d5/583/AUTH_dev/EC_cont1/obj",
"http://storage01.swiftdrive.com:6007/d7/583/AUTH_dev/EC_cont1/obj",
"http://storage02.swiftdrive.com:6007/d4/583/AUTH_dev/EC_cont1/obj",
"http://storage01.swiftdrive.com:6006/d6/583/AUTH_dev/EC_cont1/obj"
],
"headers": {
"X-Backend-Storage-Policy-Index": "2"
}
}

8
api-ref/src/wadls/object-api/src/samples/endpoints-list-response.json
View File

@ -1,8 +0,0 @@
{
"endpoints": [
"http://storage02.swiftdrive:6002/d2/617/AUTH_dev",
"http://storage01.swiftdrive:6002/d8/617/AUTH_dev",
"http://storage01.swiftdrive:6002/d11/617/AUTH_dev"
],
"headers": {}
}

1
api-ref/src/wadls/object-api/src/samples/goodbyeworld.txt
View File

@ -1 +0,0 @@
Goodbye World!

1
api-ref/src/wadls/object-api/src/samples/helloworld.txt
View File

@ -1 +0,0 @@
Hello World Again!

10
api-ref/src/wadls/object-api/src/samples/objects-list-http-response-json.txt
View File

@ -1,10 +0,0 @@
HTTP/1.1 200 OK
Content-Length: 341
X-Container-Object-Count: 2
Accept-Ranges: bytes
X-Container-Meta-Book: TomSawyer
X-Timestamp: 1389727543.65372
X-Container-Bytes-Used: 26
Content-Type: application/json; charset=utf-8
X-Trans-Id: tx26377fe5fab74869825d1-0052d6bdff
Date: Wed, 15 Jan 2014 16:57:35 GMT

10
api-ref/src/wadls/object-api/src/samples/objects-list-http-response-xml.txt
View File

@ -1,10 +0,0 @@
HTTP/1.1 200 OK
Content-Length: 500
X-Container-Object-Count: 2
Accept-Ranges: bytes
X-Container-Meta-Book: TomSawyer
X-Timestamp: 1389727543.65372
X-Container-Bytes-Used: 26
Content-Type: application/xml; charset=utf-8
X-Trans-Id: txc75ea9a6e66f47d79e0c5-0052d6be76
Date: Wed, 15 Jan 2014 16:59:35 GMT

16
api-ref/src/wadls/object-api/src/samples/objects-list-response.json
View File

@ -1,16 +0,0 @@
[
{
"hash": "451e372e48e0f6b1114fa0724aa79fa1",
"last_modified": "2014-01-15T16:41:49.390270",
"bytes": 14,
"name": "goodbye",
"content_type": "application/octet-stream"
},
{
"hash": "ed076287532e86365e841e92bfc50d8c",
"last_modified": "2014-01-15T16:37:43.427570",
"bytes": 12,
"name": "helloworld",
"content_type": "application/octet-stream"
}
]

17
api-ref/src/wadls/object-api/src/samples/objects-list-response.xml
View File

@ -1,17 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<container name="marktwain">
<object>
<name>goodbye</name>
<hash>451e372e48e0f6b1114fa0724aa79fa1</hash>
<bytes>14</bytes>
<content_type>application/octet-stream</content_type>
<last_modified>2014-01-15T16:41:49.390270</last_modified>
</object>
<object>
<name>helloworld</name>
<hash>ed076287532e86365e841e92bfc50d8c</hash>
<bytes>12</bytes>
<content_type>application/octet-stream</content_type>
<last_modified>2014-01-15T16:37:43.427570</last_modified>
</object>
</container>

2
www/static/.htaccess
View File

@ -22,3 +22,5 @@ redirect 301 /api-ref-image-v2.html /api-ref/image/index.html
# Redirect WADL-based Networking API docs to in-tree docs
redirect 301 /api-ref-networking-v2.html /api-ref/networking/v2/index.html
redirect 301 /api-ref-networking-v2-ext.html /api-ref/networking/v2-ext/index.html
# Redirect WADL-based Object Storage API docs to in-tree docs
redirect 301 /api-ref-objectstorage-v1.html /api-ref/object-storage/index.html