Corrections for the API specifications in api-ref

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

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

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

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

Change-Id: I315b4e550b7d10880fbc00fce9311127ba609c2d

8 files changed, 575 insertions, 392 deletions

diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index 5b4e643f1..22f40d575 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -6,8 +6,10 @@
 
 .. rest_expand_all::
 
+.. include:: storage_info.inc
 .. include:: storage-account-services.inc
-.. include:: storage_endpoints.inc
-.. include:: storage-object-services.inc
 .. include:: storage-container-services.inc
-.. include:: storage_info.inc
+.. include:: storage-object-services.inc
+.. include:: storage_endpoints.inc
+
+
diff --git a/api-ref/source/metadata_header_encoding.inc b/api-ref/source/metadata_header_encoding.inc
new file mode 100644
index 000000000..f10ae806a
--- /dev/null
+++ b/api-ref/source/metadata_header_encoding.inc
@@ -0,0 +1,4 @@
+The metadata value must be UTF-8-encoded and then
+URL-encoded before you include it in the header.
+This is a direct violation of the HTTP/1.1 `basic rules
+<http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2>`_.
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 28e7a93e4..d4c79e8e4 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -22,9 +22,9 @@ Content-Disposition:
   in: header
   required: false
   type: string
-Content-Disposition_1:
+Content-Disposition_resp:
   description: |
-    If set, specifies the override behavior for the
+    If present, specifies the override behavior for the
     browser. For example, this header might specify that the browser
     use a download program to save this file rather than show the
     file, which is the default.  If not set, this header is not
@@ -39,37 +39,36 @@ Content-Encoding:
   in: header
   required: false
   type: string
-Content-Encoding_1:
+Content-Encoding_resp:
   description: |
-    If set, the value of the ``Content-Encoding``
+    If present, the value of the ``Content-Encoding``
     metadata.  If not set, the operation does not return this header.
   in: header
   required: false
   type: string
-Content-Length:
+Content-Length_cud_resp:
   description: |
     If the operation succeeds, this value is zero
-    (0). If the operation fails, this value is the length of the error
+    (0) or the length of informational or error
     text in the response body.
   in: header
   required: true
   type: string
-Content-Length_1:
+Content-Length_get_resp:
   description: |
-    Set to the length of the object content. Do not
-    set if chunked transfer encoding is being used.
+    The length of the object content in the response
+    body, in bytes.
   in: header
-  required: false
-  type: integer
-Content-Length_2:
+  required: true
+  type: string
+Content-Length_listing_resp:
   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.
+    If the operation succeeds, the length of the response body
+    in bytes. On error, this is the length of the error text.
   in: header
   required: true
   type: string
-Content-Length_3:
+Content-Length_obj_head_resp:
   description: |
     HEAD operations do not return content. The
     ``Content-Length`` header value is not the size of the response
@@ -77,57 +76,48 @@ Content-Length_3:
   in: header
   required: true
   type: string
-Content-Length_4:
+Content-Length_put_req:
   description: |
-    The length of the object content in the response
-    body, in bytes.
+    Set to the length of the object content (i.e. the length in bytes
+    of the request body). Do not
+    set if chunked transfer encoding is being used.
   in: header
-  required: true
-  type: string
-Content-Type:
+  required: false
+  type: integer
+Content-Type_cud_resp:
   description: |
-    Changes the MIME type for the object.
+    If present, this value is the MIME
+    type of the informational or error text in the response body.
   in: header
   required: false
   type: string
-Content-Type_1:
+Content-Type_listing_resp:
   description: |
-    If the operation fails, this value is the MIME
-    type of the error text in the response body.
+    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
-Content-Type_2:
+Content-Type_obj_cu_req:
   description: |
-    The MIME type of the object.
+    Sets the MIME type for the object.
   in: header
-  required: true
+  required: false
   type: string
-Content-Type_3:
+Content-Type_obj_resp:
   description: |
-    The MIME type of the list of names. If the
-    operation fails, this value is the MIME type of the error text in
-    the response body.
+    The MIME type of the object.
   in: header
   required: true
   type: string
 Date:
   description: |
-    The transaction date and time.
-
-    The date and time stamp format is `ISO 8601
-    <https://en.wikipedia.org/wiki/ISO_8601>`_:
-
-    ::
-
-       CCYY-MM-DDThh:mm:ss±hh:mm
-
-    For example, ``2015-08-27T09:49:58-05:00``.
-
-    The ``±hh:mm`` value, if included, is the time zone as an offset
-    from UTC. In the previous example, the offset value is ``-05:00``.
-
-    A ``null`` value indicates that the token never expires.
+    The date and time the system responded to the request,
+    using the preferred format of
+    `RFC 7231 <https://tools.ietf.org/html/rfc7231#section-7.1.1.1>`_ as
+    shown in this example ``Thu, 16 Jun 2016 15:10:38 GMT``. The time is
+    always in UTC.
   in: header
   required: true
   type: string
@@ -140,14 +130,29 @@ Destination:
   in: header
   required: true
   type: string
-ETag:
+Destination-Account:
+  description: |
+    Specifies the account name where the object is copied to. If not
+    specified, the object is copied to the account which owns the object
+    (i.e., the account in the path).
+  in: header
+  required: false
+  type: string
+ETag_obj_copied:
   description: |
     The MD5 checksum of the copied object content.
     The value is not quoted.
   in: header
   required: true
   type: string
-ETag_1:
+ETag_obj_received:
+  description: |
+    The MD5 checksum of the uploaded object content.
+    The value is not quoted.
+  in: header
+  required: true
+  type: string
+ETag_obj_req:
   description: |
     The MD5 checksum value of the request body. For
     example, the MD5 checksum value of the object content. You are
@@ -158,7 +163,7 @@ ETag_1:
   in: header
   required: false
   type: string
-ETag_2:
+ETag_obj_resp:
   description: |
     For objects smaller than 5 GB, this value is the
     MD5 checksum of the object content. The value is not quoted.  For
@@ -190,7 +195,7 @@ If-Modified-Since:
 If-None-Match:
   description: |
     In combination with ``Expect: 100-Continue``,
-    specify an ``"If- None-Match: *"`` header to query whether the
+    specify an ``"If-None-Match: *"`` header to query whether the
     server already has a copy of the object before any data is sent.
   in: header
   required: false
@@ -205,19 +210,10 @@ If-Unmodified-Since:
 Last-Modified:
   description: |
     The date and time when the object was created or its metadata was
-    changed.
+    changed. The date and time is formaatted as shown in this
+    example: ``Fri, 12 Aug 2016 14:24:16 GMT``
 
-    The date and time stamp format is `ISO 8601
-    <https://en.wikipedia.org/wiki/ISO_8601>`_:
-
-    ::
-
-       CCYY-MM-DDThh:mm:ss±hh:mm
-
-    For example, ``2015-08-27T09:49:58-05:00``.
-
-    The ``±hh:mm`` value, if included, is the time zone as an offset
-    from UTC. In the previous example, the offset value is ``-05:00``.
+    The time is always in UTC.
   in: header
   required: true
   type: string
@@ -233,18 +229,21 @@ Range:
     do, the value   defaults to the offset of the last byte of data.
     - **Suffix byte range specification**. Use LENGTH bytes to specify
     the length of the data range.  The following forms of the header
-    specify the following ranges of data:  - ``Range: bytes=-5``. The
-    last five bytes.  - ``Range: bytes=10-15``. The six bytes of data
-    after a 10-byte   offset.  - ``Range: bytes=10-15,-5``. A multi-
-    part response that contains the   last five bytes and the six
-    bytes of data after a 10-byte   offset. The ``Content-Type``
-    response header contains   ``multipart/byteranges``.  - ``Range:
-    bytes=4-6``. Bytes 4 to 6 inclusive.  - ``Range: bytes=2-2``. Byte
-    2, the third byte of the data.  - ``Range: bytes=6-``. Byte 6 and
-    after.  - ``Range: bytes=1-3,2-5``. A multi-part response that
-    contains   bytes 1 to 3 inclusive, and bytes 2 to 5 inclusive. The
-    ``Content-Type`` response header contains
-    ``multipart/byteranges``.
+    specify the following ranges of data:
+
+    - ``Range: bytes=-5``. The last five bytes.
+    - ``Range: bytes=10-15``. The six bytes of data after a 10-byte   offset.
+    - ``Range: bytes=10-15,-5``. A multi-part response that contains the
+      last five bytes and the six
+      bytes of data after a 10-byte offset. The ``Content-Type``
+      response header contains   ``multipart/byteranges``.
+    - ``Range: bytes=4-6``. Bytes 4 to 6 inclusive.
+    - ``Range: bytes=2-2``. Byte 2, the third byte of the data.
+    - ``Range: bytes=6-``. Byte 6 and after.
+    - ``Range: bytes=1-3,2-5``. A multi-part response that
+      contains   bytes 1 to 3 inclusive, and bytes 2 to 5 inclusive. The
+      ``Content-Type`` response header contains
+      ``multipart/byteranges``.
   in: header
   required: false
   type: string
@@ -272,23 +271,31 @@ X-Account-Container-Count:
 X-Account-Meta-name:
   description: |
     The custom account metadata item, where
-    ``{name}`` is the name of the metadata item.  One ``X-Account-
-    Meta- {name}`` response header appears for each metadata item (for
-    each ``{name}``).
+    ``name`` is the name of the metadata item.  One ``X-Account-Meta-name``
+    response header appears for each metadata item (for
+    each ``name``).
   in: header
   required: false
   type: string
-X-Account-Meta-name_1:
+X-Account-Meta-name_req:
   description: |
-    The account metadata. The ``{name}`` is the name
+    The account metadata. The ``name`` is the name
     of metadata item that you want to add, update, or delete. To
     delete this item, send an empty value in this header.  You must
-    specify an ``X-Account-Meta- {name}`` header for each metadata
-    item (for each ``{name}``) that you want to add, update, or
+    specify an ``X-Account-Meta-name`` header for each metadata
+    item (for each ``name``) that you want to add, update, or
     delete.
   in: header
   required: false
   type: string
+X-Account-Meta-Quota-Bytes_resp:
+  description: |
+    If present, this is the limit on the total size in bytes of objects stored
+    in the account.
+    Typically this value is set by an administrator.
+  in: header
+  required: false
+  type: string
 X-Account-Meta-Temp-URL-Key:
   description: |
     The secret key value for temporary URLs. If not
@@ -311,6 +318,28 @@ X-Account-Object-Count:
   in: header
   required: true
   type: integer
+X-Account-Storage-Policy-name-Bytes-Used:
+  description: |
+    The total number of bytes that are stored in
+    in a given storage policy, where ``name`` is the
+    name of the storage policy.
+  in: header
+  required: true
+  type: integer
+X-Account-Storage-Policy-name-Container-Count:
+  description: |
+    The number of containers in the account that use the given
+    storage policy where ``name`` is the name of the storage policy.
+  in: header
+  required: true
+  type: integer
+X-Account-Storage-Policy-name-Object-Count:
+  description: |
+    The number of objects in given storage policy where ``name`` is
+    the name of the storage policy.
+  in: header
+  required: true
+  type: integer
 X-Auth-Token:
   description: |
     Authentication token. If you omit this header,
@@ -319,12 +348,6 @@ X-Auth-Token:
   in: header
   required: false
   type: string
-X-Auth-Token_1:
-  description: |
-    Authentication token.
-  in: header
-  required: true
-  type: string
 X-Container-Bytes-Used:
   description: |
     The total number of bytes used.
@@ -359,9 +382,9 @@ X-Container-Meta-Access-Control-Expose-Headers:
     `http://www.w3.org/TR/cors/#simple-response-header
     <http://www.w3.org/TR/cors/#simple-response-header>`_.  - The
     headers ``etag``, ``x-timestamp``, ``x-trans-id``.  - All metadata
-    headers (``X-Container-Meta-*`` for containers and   ``X-Object-
-    Meta-*`` for objects) headers listed in ``X-Container-   Meta-
-    Access-Control-Expose-Headers``.
+    headers (``X-Container-Meta-*`` for containers and
+    ``X-Object-Meta-*`` for objects) headers listed in
+    ``X-Container-Meta-Access-Control-Expose-Headers``.
   in: header
   required: false
   type: string
@@ -376,21 +399,21 @@ X-Container-Meta-Access-Control-Max-Age:
   type: string
 X-Container-Meta-name:
   description: |
-    The container metadata, where ``{name}`` is the
-    name of metadata item.  You must specify an ``X-Container-Meta-
-    {name}`` header for each metadata item (for each ``{name}``) that
-    you want to add or update.
+    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: false
+  required: true
   type: string
-X-Container-Meta-name_1:
+X-Container-Meta-name_req:
   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}``).
+    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: true
+  required: false
   type: string
 X-Container-Meta-Quota-Bytes:
   description: |
@@ -398,6 +421,10 @@ X-Container-Meta-Quota-Bytes:
     Typically these values are set by an administrator. Returns a 413
     response (request entity too large) when an object PUT operation
     exceeds this quota value.
+    This value does not take effect immediately. see
+    `Container Quotas
+    <http://docs.openstack.org/developer/swift/api/container_quotas.html>`_
+    for more information.
   in: header
   required: false
   type: string
@@ -407,6 +434,10 @@ X-Container-Meta-Quota-Count:
     Typically these values are set by an administrator. Returns a 413
     response (request entity too large) when an object PUT operation
     exceeds this quota value.
+    This value does not take effect immediately. see
+    `Container Quotas
+    <http://docs.openstack.org/developer/swift/api/container_quotas.html>`_
+    for more information.
   in: header
   required: false
   type: string
@@ -431,7 +462,7 @@ X-Container-Meta-Web-Directory-Type:
     ``application/directory``. Directory marker objects are 0-byte
     objects that represent directories to create a simulated
     hierarchical structure.  For example, if you set ``"X-Container-
-    Meta-Web-Directory- Type: text/directory"``, Object Storage treats
+    Meta-Web-Directory-Type: text/directory"``, Object Storage treats
     0-byte objects with a content-type of ``text/directory`` as
     directories rather than objects.
   in: header
@@ -446,47 +477,18 @@ X-Container-Object-Count:
 X-Container-Read:
   description: |
     Sets a container access control list (ACL) that grants read access.
-    Container ACLs are available on any Object Storage cluster, and are
-    enabled by container rather than by cluster.
-
-    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:
+    The scope of the access is specific to the container. The ACL grants
+    the ability to perform GET or HEAD operations on objects in the container
+    or to perform a GET or HEAD operation on the container itself.
 
-    - ``.r:*`` All referrers.
-
-    - ``.r:example.com,swift.example.com`` Comma-separated list of
-      referrers.
-
-    - ``.rlistings`` Container listing access.
-
-    - ``AUTH_username`` Access to a user who authenticates through a
-      legacy or non-OpenStack-Identity-based authentication system.
-
-    - ``LDAP_`` Access to all users who authenticate through an LDAP-
-      based legacy or non-OpenStack-Identity-based authentication
-      system.
+    The format and scope of the ACL is dependent on the authorization system
+    used by the Object Storage service.
   in: header
   required: false
   type: string
-X-Container-Read_1:
+X-Container-Read_resp:
   description: |
-    The ACL that grants read access. If not set, this
+    The ACL that grants read access. If there is no ACL, this
     header is not returned by this operation.
   in: header
   required: false
@@ -496,10 +498,13 @@ X-Container-Sync-Key:
     Sets the secret key for container
     synchronization. If you remove the secret key, synchronization is
     halted.
+    For more information, see `Container to Container Synchronization
+    <http://docs.openstack.org/developer/swift/overview_
+    container_sync.html>`_
   in: header
   required: false
   type: string
-X-Container-Sync-Key_1:
+X-Container-Sync-Key_resp:
   description: |
     The secret key for container synchronization. If
     not set, this header is not returned by this operation.
@@ -516,7 +521,7 @@ X-Container-Sync-To:
   in: header
   required: false
   type: string
-X-Container-Sync-To_1:
+X-Container-Sync-To_resp:
   description: |
     The destination for container synchronization. If
     not set, this header is not returned by this operation.
@@ -525,13 +530,21 @@ X-Container-Sync-To_1:
   type: string
 X-Container-Write:
   description: |
-    Sets an ACL that grants write access.
+    Sets a container access control list (ACL) that grants write access.
+    The scope of the access is specific to the container. The ACL grants
+    the ability to perform PUT, POST and DELETE operations on
+    objects in the container. It does not grant write access to the container
+    metadata.
+
+    The format of the ACL is dependent on the authorization system
+    used by the Object Storage service.
+
   in: header
   required: false
   type: string
-X-Container-Write_1:
-  description: |
-    The ACL that grants write access. If not set,
+X-Container-Write_resp:
+  description:
+    The ACL that grants write access. If there is no ACL,
     this header is not returned by this operation.
   in: header
   required: false
@@ -544,6 +557,13 @@ X-Copied-From:
   in: header
   required: false
   type: string
+X-Copied-From-Account:
+  description: |
+    For a copied object, shows the account
+    from which the new object was copied.
+  in: header
+  required: false
+  type: string
 X-Copied-From-Last-Modified:
   description: |
     For a copied object, the date and time in `UNIX
@@ -572,7 +592,7 @@ X-Delete-After:
   description: |
     The number of seconds after which the system
     removes the object. Internally, the Object Storage system stores
-    this value in the ``X -Delete-At`` metadata item.
+    this value in the ``X-Delete-At`` metadata item.
   in: header
   required: false
   type: integer
@@ -585,21 +605,11 @@ X-Delete-At:
   in: header
   required: false
   type: integer
-X-Delete-At_1:
-  description: |
-    If set, the date and time in `UNIX Epoch time
-    stamp format <https://en.wikipedia.org/wiki/Unix_time>`_ when the
-    system deletes the object.  For example, ``1440619048`` is
-    equivalent to ``Mon, Wed, 26 Aug 2015 19:57:28 GMT``.  If not set,
-    this operation does not return this header.
-  in: header
-  required: false
-  type: integer
 X-Detect-Content-Type:
   description: |
     If set to ``true``, Object Storage guesses the
     content type based on the file extension and ignores the value
-    sent in the ``Content- Type`` header, if present.
+    sent in the ``Content-Type`` header, if present.
   in: header
   required: false
   type: boolean
@@ -631,9 +641,9 @@ X-Object-Manifest:
   in: header
   required: false
   type: string
-X-Object-Manifest_1:
+X-Object-Manifest_resp:
   description: |
-    If set, to this is a dynamic large object
+    If present, this is a dynamic large object
     manifest object. The value is the container and object name prefix
     of the segment objects in the form ``container/prefix``.
   in: header
@@ -641,26 +651,35 @@ X-Object-Manifest_1:
   type: string
 X-Object-Meta-name:
   description: |
-    The object metadata, where ``{name}`` is the name
-    of the metadata item.  You must specify an ``X-Object-Meta-
-    {name}`` header for each metadata ``{name}`` item that you want to
-    add or update.
+    The object metadata, where ``name`` is the name
+    of the metadata item.  You must specify an
+    ``X-Object-Meta-name`` header for each metadata ``name`` item that
+    you want to add or update.
   in: header
   required: false
   type: string
-X-Object-Meta-name_1:
+X-Object-Meta-name_resp:
   description: |
-    The custom object metadata item, where ``{name}``
-    is the name of the metadata item.  One ``X-Object-Meta- {name}``
-    response header appears for each metadata ``{name}`` item.
+    If present, the custom object metadata item, where ``name``
+    is the name of the metadata item.  One``X-Object-Meta-name``
+    response header appears for each metadata ``name`` item.
   in: header
-  required: true
+  required: false
+  type: string
+X-Remove-Account-name:
+  description: |
+    Removes the metadata item named ``name``.
+    For example, ``X-Remove-Account-Meta-Blue`` removes
+    custom metadata.
+  in: header
+  required: false
   type: string
 X-Remove-Container-name:
   description: |
-    Removes the metadata item named ``{name}``. For
-    example, ``X -Remove-Container-Read`` removes the ``X-Container-
-    Read`` metadata item.
+    Removes the metadata item named ``name``. For
+    example, ``X-Remove-Container-Read`` removes the
+    ``X-Container-Read`` metadata item and ``X-Remove-Container-Meta-Blue``
+    removes custom metadata.
   in: header
   required: false
   type: string
@@ -670,6 +689,14 @@ X-Remove-Versions-Location:
   in: header
   required: false
   type: string
+X-Service-Token:
+  description: |
+    A service token. See `OpenStack Service Using Composite Tokens
+    <http://docs.openstack.org/developer/swift/overview_auth.html#openstack-
+    service-using-composite-tokens>`_ for more information.
+  in: header
+  required: false
+  type: string
 X-Static-Large-Object:
   description: |
     Set to ``true`` if this object is a static large
@@ -677,6 +704,14 @@ X-Static-Large-Object:
   in: header
   required: true
   type: boolean
+X-Storage-Policy:
+  description: |
+    In requests, specifies the name of the storage policy to use for
+    the container. In responses, is the storage policy name.
+    The storage policy of the container cannot be changed.
+  in: header
+  required: false
+  type: string
 X-Timestamp:
   description: |
     The date and time in `UNIX Epoch time stamp
@@ -696,23 +731,23 @@ X-Trans-Id:
   type: string
 X-Trans-Id-Extra:
   description: |
-    Extra transaction information. Use the ``X-Trans-
-    Id-Extra`` request header to include extra information to help you
+    Extra transaction information. Use the ``X-Trans-Id-Extra``
+    request header to include extra information to help you
     debug any errors that might occur with large object upload and
     other Object Storage transactions.  Object Storage appends the
-    first 32 characters of the ``X-Trans-Id- Extra`` request header
+    first 32 characters of the ``X-Trans-Id-Extra`` request header
     value to the transaction ID value in the generated ``X-Trans-Id``
     response header. You must UTF-8-encode and then URL-encode the
     extra transaction information before you include it in the ``X
     -Trans-Id-Extra`` request header.  For example, you can include
     extra transaction information when you upload `large objects
-    <http://docs.openstack.org/user-
-    guide/cli_swift_large_object_creation.html>`_ such as images. When
+    <http://docs.openstack.org/developer/swift/api/large_objects.html>`_
+    such as images. When
     you upload each segment and the manifest, include the same value
     in the ``X-Trans-Id-Extra`` request header. If an error occurs,
     you can find all requests that are related to the large object
-    upload in the Object Storage logs.  You can also use ``X-Trans-Id-
-    Extra`` strings to help operators debug requests that fail to
+    upload in the Object Storage logs.  You can also use ``X-Trans-Id-Extra``
+    strings to help operators debug requests that fail to
     receive responses. The operator can search for the extra
     information in the logs.
   in: header
@@ -728,6 +763,16 @@ X-Versions-Location:
   in: header
   required: false
   type: string
+X-Versions-Location_resp:
+  description: |
+    If present, this container has versioning enabled and the value
+    is the UTF-8 encoded name of another container.
+    For more information about object versioning,
+    see `Object versioning <http://docs.openstack.org/developer/
+    swift/api/object_versioning.html>`_.
+  in: header
+  required: false
+  type: string
 X-Versions-Mode:
   description: |
     The versioning mode for this container. The value must be either
@@ -739,6 +784,15 @@ X-Versions-Mode:
   in: header
   required: false
   type: string
+X-Versions-Mode_resp:
+  description: |
+    If set, this is the versioning mode for this container. The value is either
+    ``stack`` or ``history``. For more information about object versioning,
+    see `Object versioning <http://docs.openstack.org/developer/
+    swift/api/object_versioning.html>`_.
+  in: header
+  required: false
+  type: string
 
 # variables in path
 account:
@@ -750,12 +804,13 @@ account:
   type: string
 container:
   description: |
-    The unique name for the container.  The container
+    The unique (within an account) name for the container.  The container
     name must be from 1 to 256 characters long and can start with any
     character and contain any pattern. Character set must be UTF-8.
     The container name cannot contain a slash (``/``) character
     because this character delimits the container and object name. For
-    example, ``/account/container/object``.
+    example, the path ``/v1/account/www/pages`` specifies the ``www``
+    container, not the ``www/pages`` container.
   in: path
   required: false
   type: string
@@ -767,6 +822,16 @@ object:
   type: string
 
 # variables in query
+bulk-delete:
+  description: |
+    When the ``bulk-delete`` query parameter is present in the POST
+    request, multiple objects or containers can be deleted
+    with a single request. See `Bulk Delete
+    <http://docs.openstack.org/developer/swift/middleware.html?highlight=
+    bulk#bulk-delete>`_ for how this feature is used.
+  in: query
+  required: false
+  type: string
 delimiter:
   description: |
     Delimiter value, which returns the object names
@@ -784,6 +849,16 @@ end_marker:
   in: query
   required: false
   type: string
+extract-archive:
+  description: |
+    When the ``extract-archive`` query parameter is present in the POST
+    request, an archive (tar file) is uploaded and extracted to
+    create multiple objects. See `Extract Archive
+    <http://docs.openstack.org/developer/swift/middleware.html?highlight=
+    bulk#extract-archive>`_ for how this feature is used.
+  in: query
+  required: false
+  type: string
 filename:
   description: |
     Overrides the default file name. Object Storage
@@ -823,23 +898,24 @@ marker:
   in: query
   required: false
   type: string
-multipart-manifest:
+multipart-manifest_copy:
   description: |
-    If ``?multipart-manifest=put``, the object is a
-    static large object manifest and the body contains the manifest.
+    If you include the ``multipart-manifest=get``
+    query parameter and the object is a large object, the object
+    contents are not copied. Instead, the manifest is copied to
+    the new object.
   in: query
   required: false
   type: string
-multipart-manifest_1:
+multipart-manifest_delete:
   description: |
     If you include the ``multipart-manifest=delete``
     query parameter and the object is a static large object, the
     segment objects and manifest object are deleted. If you omit the
-    ``multipart- manifest=delete`` query parameter and the object is a
+    ``multipart-manifest=delete`` query parameter and the object is a
     static large object, the manifest object is deleted but the
-    segment objects are not deleted.  For a bulk delete, the response
-    body looks the same as it does for a normal bulk delete. In
-    contrast, a plain object DELETE response has an empty body.
+    segment objects are not deleted.  The response body will contain
+    the status of the deletion of every processed segment object.
   in: query
   required: false
   type: string
@@ -862,6 +938,13 @@ multipart-manifest_head:
   in: query
   required: false
   type: string
+multipart-manifest_put:
+  description: |
+    If you include the ``multipart-manifest=put`` query parameter, the object
+    is a static large object manifest and the body contains the manifest.
+  in: query
+  required: false
+  type: string
 path:
   description: |
     For a string value, returns the object names that
@@ -878,11 +961,9 @@ prefix:
   type: string
 swiftinfo_expires:
   description: |
-    Filters the response by the expiration date and
-    time in `UNIX Epoch time stamp format
-    <https://en.wikipedia.org/wiki/Unix_time>`_.  For example,
-    ``1440619048`` is equivalent to ``Mon, Wed, 26 Aug 2015 19:57:28
-    GMT``.
+    The time at which ``swiftinfo_sig`` expires. The time is in
+    `UNIX Epoch time stamp format
+    <https://en.wikipedia.org/wiki/Unix_time>`_.
   in: query
   required: false
   type: integer
diff --git a/api-ref/source/samples/capabilities-list-response.json b/api-ref/source/samples/capabilities-list-response.json
index bcc91f7d5..f082dc7b9 100644
--- a/api-ref/source/samples/capabilities-list-response.json
+++ b/api-ref/source/samples/capabilities-list-response.json
@@ -2,6 +2,11 @@
     "swift": {
         "version": "1.11.0"
     },
+    "slo": {
+        "max_manifest_segments": 1000,
+        "max_manifest_size": 2097152,
+        "min_segment_size": 1
+    },
     "staticweb": {},
     "tempurl": {}
 }
diff --git a/api-ref/source/storage-account-services.inc b/api-ref/source/storage-account-services.inc
index 17f228c54..4a543787c 100644
--- a/api-ref/source/storage-account-services.inc
+++ b/api-ref/source/storage-account-services.inc
@@ -5,60 +5,10 @@ Accounts
 ========
 
 Lists containers for an account. Creates, updates, shows, and
-deletes account metadata.
+deletes account metadata. For more information and concepts about
+accounts see `Object Storage API overview
+<http://docs.openstack.org/developer/swift/api/object_api_v1_overview.html>`_.
 
-Account metadata operations work differently than container and
-object metadata operations work. Depending on the contents of your
-POST account metadata request, the Object Storage API updates the
-metadata in one of these ways:
-
-**Account metadata operations**
-
-+----------------------------------------------------------+---------------------------------------------------------------+
-| POST request body contains                               | Description                                                   |
-+----------------------------------------------------------+---------------------------------------------------------------+
-| A metadata key without a value.                          | The API removes the metadata item from the account.           |
-|                                                          |                                                               |
-| The metadata key already exists for the account.         |                                                               |
-+----------------------------------------------------------+---------------------------------------------------------------+
-| A metadata key without a value.                          | The API ignores the metadata key.                             |
-|                                                          |                                                               |
-| The metadata key does not already exist for the account. |                                                               |
-+----------------------------------------------------------+---------------------------------------------------------------+
-| A metadata key value.                                    | The API updates the metadata key value for the account.       |
-|                                                          |                                                               |
-| The metadata key already exists for the account.         |                                                               |
-+----------------------------------------------------------+---------------------------------------------------------------+
-| A metadata key value.                                    | The API adds the metadata key and value pair, or item, to the |
-|                                                          | account.                                                      |
-| The metadata key does not already exist for the account. |                                                               |
-+----------------------------------------------------------+---------------------------------------------------------------+
-| One or more account metadata items are omitted.          | The API does not change the existing metadata items.          |
-|                                                          |                                                               |
-| The metadata items already exist for the account.        |                                                               |
-+----------------------------------------------------------+---------------------------------------------------------------+
-
-
-
-For these requests, specifying the ``X-Remove-Account-Meta-*``
-request header for the key with any value is equivalent to
-specifying the ``X-Account-Meta-*`` request header with an empty
-value.
-
-Metadata keys must be treated as case-insensitive at all times.
-These keys can contain ASCII 7-bit characters that are not control
-(0-31) characters, DEL, or a separator character, according to
-`HTTP/1.1 <http://www.w3.org/Protocols/rfc2616/rfc2616.html>`_ .
-Also, Object Storage does not support the underscore character,
-which it silently converts to a hyphen.
-
-The metadata values in Object Storage do not follow HTTP/1.1 rules
-for character encodings. You must use a UTF-8 encoding to get a
-byte array for any string that contains characters that are not in
-the 7-bit ASCII 0-127 range. Otherwise, Object Storage returns the
-404 response code for ISO-8859-1 characters in the 128-255 range,
-which is a direct violation of the HTTP/1.1 `basic rules
-<http://www.w3.org/Protocols/rfc2616/rfc2616-sec2.html#sec2.2>`_.
 
 
 Show account details and list containers
@@ -135,6 +85,7 @@ Request
    - prefix: prefix
    - delimiter: delimiter
    - X-Auth-Token: X-Auth-Token
+   - X-Service-Token: X-Service-Token
    - X-Newest: X-Newest
    - Accept: Accept
    - X-Trans-Id-Extra: X-Trans-Id-Extra
@@ -145,30 +96,39 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - Content-Length: Content-Length
+   - Content-Length: Content-Length_listing_resp
    - X-Account-Meta-name: X-Account-Meta-name
-   - X-Account-Object-Count: X-Account-Object-Count
+   - X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key
    - X-Account-Meta-Temp-URL-Key-2: X-Account-Meta-Temp-URL-Key-2
    - X-Timestamp: X-Timestamp
-   - X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key
    - X-Trans-Id: X-Trans-Id
    - Date: Date
    - X-Account-Bytes-Used: X-Account-Bytes-Used
    - X-Account-Container-Count: X-Account-Container-Count
-   - Content-Type: Content-Type
+   - X-Account-Object-Count: X-Account-Object-Count
+   - X-Account-Storage-Policy-name-Bytes-Used: X-Account-Storage-Policy-name-Bytes-Used
+   - X-Account-Storage-Policy-name-Container-Count: X-Account-Storage-Policy-name-Container-Count
+   - X-Account-Storage-Policy-name-Object-Count: X-Account-Storage-Policy-name-Object-Count
+   - X-Account-Meta-Quota-Bytes: X-Account-Meta-Quota-Bytes_resp
+   - Content-Type: Content-Type_listing_resp
    - count: count
    - bytes: bytes
    - name: name
 
 
 
-Response Example
-----------------
+Response Example format=json
+----------------------------
 
-.. literalinclude:: samples/account-containers-list-http-response-xml.txt
-   :language: javascript
+.. literalinclude:: samples/account-containers-list-http-response-json.txt
+.. literalinclude:: samples/account-containers-list-response.json
 
 
+Response Example format=xml
+---------------------------
+
+.. literalinclude:: samples/account-containers-list-http-response-xml.txt
+.. literalinclude:: samples/account-containers-list-response.xml
 
 
 
@@ -179,21 +139,62 @@ Create, update, or delete account metadata
 
 Creates, updates, or deletes account metadata.
 
-To create, update, or delete metadata, use the ``X-Account-
-Meta-{name}`` request header, where ``{name}`` is the name of the
+To create, update, or delete custom metadata, use the
+``X-Account-Meta-{name}`` request header, where ``{name}`` is the name of the
 metadata item.
 
-Subsequent requests for the same key and value pair overwrite the
-existing value.
+Account metadata operations work differently than how
+object metadata operations work. Depending on the contents of your
+POST account metadata request, the Object Storage API updates the
+metadata as shown in the following table:
+
+**Account metadata operations**
+
++----------------------------------------------------------+---------------------------------------------------------------+
+| POST request header contains                             | Result                                                        |
++----------------------------------------------------------+---------------------------------------------------------------+
+| A metadata key without a value.                          | The API removes the metadata item from the account.           |
+|                                                          |                                                               |
+| The metadata key already exists for the account.         |                                                               |
++----------------------------------------------------------+---------------------------------------------------------------+
+| A metadata key without a value.                          | The API ignores the metadata key.                             |
+|                                                          |                                                               |
+| The metadata key does not already exist for the account. |                                                               |
++----------------------------------------------------------+---------------------------------------------------------------+
+| A metadata key value.                                    | The API updates the metadata key value for the account.       |
+|                                                          |                                                               |
+| The metadata key already exists for the account.         |                                                               |
++----------------------------------------------------------+---------------------------------------------------------------+
+| A metadata key value.                                    | The API adds the metadata key and value pair, or item, to the |
+|                                                          | account.                                                      |
+| The metadata key does not already exist for the account. |                                                               |
++----------------------------------------------------------+---------------------------------------------------------------+
+| One or more account metadata items are omitted.          | The API does not change the existing metadata items.          |
+|                                                          |                                                               |
+| The metadata items already exist for the account.        |                                                               |
++----------------------------------------------------------+---------------------------------------------------------------+
+
+
 
 To delete a metadata header, send an empty value for that header,
 such as for the ``X-Account-Meta-Book`` header. If the tool you use
 to communicate with Object Storage, such as an older version of
 cURL, does not support empty headers, send the ``X-Remove-Account-
-Meta-{name}`` header with an arbitrary value. For example, ``X
--Remove-Account-Meta-Book: x``. The operation ignores the arbitrary
+Meta-{name}`` header with an arbitrary value. For example,
+``X-Remove-Account-Meta-Book: x``. The operation ignores the arbitrary
 value.
 
+Metadata keys (the name of the metadata) must be treated as case-insensitive
+at all times. These keys can contain ASCII 7-bit characters that are not
+control (0-31) characters, DEL, or a separator character, according to
+`HTTP/1.1 <http://www.w3.org/Protocols/rfc2616/rfc2616.html>`_ .
+The underscore character is silently converted to a hyphen.
+
+.. include:: metadata_header_encoding.inc
+
+Subsequent requests for the same key and value pair overwrite the
+existing value.
+
 If the container already has other custom metadata items, a request
 to create, update, or delete metadata does not affect those items.
 
@@ -270,11 +271,11 @@ Request
 
    - account: account
    - X-Auth-Token: X-Auth-Token
+   - X-Service-Token: X-Service-Token
    - X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key
    - X-Account-Meta-Temp-URL-Key-2: X-Account-Meta-Temp-URL-Key-2
-   - X-Account-Meta-name: X-Account-Meta-name
-   - Content-Type: Content-Type
-   - X-Detect-Content-Type: X-Detect-Content-Type
+   - X-Account-Meta-name: X-Account-Meta-name_req
+   - X-Remove-Account-name: X-Remove-Account-name
    - X-Trans-Id-Extra: X-Trans-Id-Extra
 
 
@@ -285,8 +286,8 @@ Response Parameters
 
    - Date: Date
    - X-Timestamp: X-Timestamp
-   - Content-Length: Content-Length
-   - Content-Type: Content-Type
+   - Content-Length: Content-Length_cud_resp
+   - Content-Type: Content-Type_cud_resp
    - X-Trans-Id: X-Trans-Id
 
 
@@ -353,6 +354,7 @@ Request
 
    - account: account
    - X-Auth-Token: X-Auth-Token
+   - X-Service-Token: X-Service-Token
    - X-Newest: X-Newest
    - X-Trans-Id-Extra: X-Trans-Id-Extra
 
@@ -362,17 +364,21 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - Content-Length: Content-Length
+   - Content-Length: Content-Length_cud_resp
    - X-Account-Meta-name: X-Account-Meta-name
-   - X-Account-Object-Count: X-Account-Object-Count
+   - X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key
    - X-Account-Meta-Temp-URL-Key-2: X-Account-Meta-Temp-URL-Key-2
    - X-Timestamp: X-Timestamp
-   - X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key
    - X-Trans-Id: X-Trans-Id
    - Date: Date
    - X-Account-Bytes-Used: X-Account-Bytes-Used
+   - X-Account-Object-Count: X-Account-Object-Count
    - X-Account-Container-Count: X-Account-Container-Count
-   - Content-Type: Content-Type
+   - X-Account-Storage-Policy-name-Bytes-Used: X-Account-Storage-Policy-name-Bytes-Used
+   - X-Account-Storage-Policy-name-Container-Count: X-Account-Storage-Policy-name-Container-Count
+   - X-Account-Storage-Policy-name-Object-Count: X-Account-Storage-Policy-name-Object-Count
+   - X-Account-Meta-Quota-Bytes: X-Account-Meta-Quota-Bytes_resp
+   - Content-Type: Content-Type_cud_resp
 
 
 
diff --git a/api-ref/source/storage-container-services.inc b/api-ref/source/storage-container-services.inc
index 2213a7884..a97967532 100644
--- a/api-ref/source/storage-container-services.inc
+++ b/api-ref/source/storage-container-services.inc
@@ -6,7 +6,9 @@ Containers
 
 Lists objects in a container. Creates, shows details for, and
 deletes containers. Creates, updates, shows, and deletes container
-metadata.
+metadata. For more information and concepts about
+containers see `Object Storage API overview
+<http://docs.openstack.org/developer/swift/api/object_api_v1_overview.html>`_.
 
 
 Show container details and list objects
@@ -17,8 +19,8 @@ Show container details and list objects
 Shows details for a container and lists objects, sorted by name, in the container.
 
 Specify query parameters in the request to filter the list and
-return a subset of object names. Omit query parameters to return
-the complete list of object names that are stored in the container,
+return a subset of objects. Omit query parameters to return
+a list of objects that are stored in the container,
 up to 10,000 names. The 10,000 maximum value is configurable. To
 view the value for the cluster, issue a GET ``/info`` request.
 
@@ -28,23 +30,13 @@ Example requests and responses:
 
 - ``No Content (204)``. Success. The response body shows no objects.
   Either the container has no objects or you are paging through a
-  long list of names by using the ``marker``, ``limit``, or
+  long list of objects by using the ``marker``, ``limit``, or
   ``end_marker`` query parameter and you have reached the end of
   the list.
 
 If the container does not exist, the call returns the ``Not Found
 (404)`` response code.
 
-The operation returns the ``Range Not Satisfiable (416)`` response
-code for any ranged GET requests that specify more than:
-
-- Fifty ranges.
-
-- Three overlapping ranges.
-
-- Eight non-increasing ranges.
-
-
 Normal response codes: 200
 Error response codes:416,404,204,
 
@@ -64,11 +56,13 @@ Request
    - delimiter: delimiter
    - path: path
    - X-Auth-Token: X-Auth-Token
+   - X-Service-Token: X-Service-Token
    - X-Newest: X-Newest
    - Accept: Accept
    - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key
    - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2
    - X-Trans-Id-Extra: X-Trans-Id-Extra
+   - X-Storage-Policy: X-Storage-Policy
 
 
 Response Parameters
@@ -77,35 +71,42 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - X-Container-Meta-name: X-Container-Meta-name
-   - Content-Length: Content-Length
+   - Content-Length: Content-Length_listing_resp
    - X-Container-Object-Count: X-Container-Object-Count
+   - X-Container-Bytes-Used: X-Container-Bytes-Used
    - Accept-Ranges: Accept-Ranges
    - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key
-   - X-Container-Bytes-Used: X-Container-Bytes-Used
    - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2
+   - X-Storage-Policy: X-Storage-Policy
+   - X-Container-Read: X-Container-Read_resp
+   - X-Container-Write: X-Container-Write_resp
+   - X-Container-Sync-Key: X-Container-Sync-Key_resp
+   - X-Container-Sync-To: X-Container-Sync-To_resp
+   - X-Versions-Location: X-Versions-Location_resp
+   - X-Versions-Mode: X-Versions-Mode_resp
    - X-Timestamp: X-Timestamp
    - X-Trans-Id: X-Trans-Id
+   - Content_Type: Content-Type_listing_resp
    - Date: Date
-   - Content-Type: Content-Type
    - hash: hash
    - last_modified: last_modified
+   - content_type: content_type
    - bytes: bytes
    - name: name
-   - content_type: content_type
-
-
-
-Response Example
-----------------
-
-.. literalinclude:: samples/objects-list-http-response-xml.txt
-   :language: javascript
 
 
+Response Example format=json
+----------------------------
 
+.. literalinclude:: samples/objects-list-http-response-json.txt
+.. literalinclude:: samples/objects-list-response.json
 
 
+Response Example format=xml
+---------------------------
 
+.. literalinclude:: samples/objects-list-http-response-xml.txt
+.. literalinclude:: samples/objects-list-response.xml
 
 Create container
 ================
@@ -119,6 +120,18 @@ issuing a PUT operation because the operation is idempotent: It
 creates a container or updates an existing container, as
 appropriate.
 
+To create, update, or delete a custom metadata item, use the ``X
+-Container-Meta-{name}`` header, where ``{name}`` is the name of
+the metadata item.
+
+Metadata keys (the name of the metadata) must be treated as case-insensitive
+at all times. These keys can contain ASCII 7-bit characters that are not
+control (0-31) characters, DEL, or a separator character, according to
+`HTTP/1.1 <http://www.w3.org/Protocols/rfc2616/rfc2616.html>`_ .
+The underscore character is silently converted to a hyphen.
+
+.. include:: metadata_header_encoding.inc
+
 Example requests and responses:
 
 - Create a container with no metadata:
@@ -156,6 +169,22 @@ Example requests and responses:
      X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37
      Date: Tue, 14 Jan 2014 19:25:43 GMT
 
+- Create a container with an ACL to allow anybody to get an object in the
+  marktwain container:
+  ::
+
+     curl -i $publicURL/marktwain -X PUT -H "X-Auth-Token: $token" -H "X-Container-Read: .r:*"
+
+
+
+  ::
+
+     HTTP/1.1 201 Created
+     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,
 
 
@@ -167,21 +196,21 @@ Request
    - account: account
    - container: container
    - X-Auth-Token: X-Auth-Token
+   - X-Service-Token: X-Service-Token
    - X-Container-Read: X-Container-Read
    - X-Container-Write: X-Container-Write
    - X-Container-Sync-To: X-Container-Sync-To
    - X-Container-Sync-Key: X-Container-Sync-Key
    - X-Versions-Location: X-Versions-Location
    - X-Versions-Mode: X-Versions-Mode
-   - X-Container-Meta-name: X-Container-Meta-name
+   - X-Container-Meta-name: X-Container-Meta-name_req
    - X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin
    - X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age
    - X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers
-   - Content-Type: Content-Type
-   - X-Detect-Content-Type: X-Detect-Content-Type
    - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key
    - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2
    - X-Trans-Id-Extra: X-Trans-Id-Extra
+   - X-Storage-Policy: X-Storage-Policy
 
 
 Response Parameters
@@ -191,8 +220,8 @@ Response Parameters
 
    - Date: Date
    - X-Timestamp: X-Timestamp
-   - Content-Length: Content-Length
-   - Content-Type: Content-Type
+   - Content-Length: Content-Length_cud_resp
+   - Content-Type: Content-Type_cud_resp
    - X-Trans-Id: X-Trans-Id
 
 
@@ -211,6 +240,14 @@ To create, update, or delete a custom metadata item, use the ``X
 -Container-Meta-{name}`` header, where ``{name}`` is the name of
 the metadata item.
 
+Metadata keys (the name of the metadata) must be treated as case-insensitive
+at all times. These keys can contain ASCII 7-bit characters that are not
+control (0-31) characters, DEL, or a separator character, according to
+`HTTP/1.1 <http://www.w3.org/Protocols/rfc2616/rfc2616.html>`_ .
+The underscore character is silently converted to a hyphen.
+
+.. include:: metadata_header_encoding.inc
+
 Subsequent requests for the same key and value pair overwrite the
 previous value.
 
@@ -297,6 +334,7 @@ Request
    - account: account
    - container: container
    - X-Auth-Token: X-Auth-Token
+   - X-Service-Token: X-Service-Token
    - X-Container-Read: X-Container-Read
    - X-Remove-Container-name: X-Remove-Container-name
    - X-Container-Write: X-Container-Write
@@ -305,15 +343,13 @@ Request
    - X-Versions-Location: X-Versions-Location
    - X-Versions-Mode: X-Versions-Mode
    - X-Remove-Versions-Location: X-Remove-Versions-Location
-   - X-Container-Meta-name: X-Container-Meta-name
+   - X-Container-Meta-name: X-Container-Meta-name_req
    - X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin
    - X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age
    - X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers
    - X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes
    - X-Container-Meta-Quota-Count: X-Container-Meta-Quota-Count
    - X-Container-Meta-Web-Directory-Type: X-Container-Meta-Web-Directory-Type
-   - Content-Type: Content-Type
-   - X-Detect-Content-Type: X-Detect-Content-Type
    - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key
    - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2
    - X-Trans-Id-Extra: X-Trans-Id-Extra
@@ -326,8 +362,8 @@ Response Parameters
 
    - Date: Date
    - X-Timestamp: X-Timestamp
-   - Content-Length: Content-Length
-   - Content-Type: Content-Type
+   - Content-Length: Content-Length_cud_resp
+   - Content-Type: Content-Type_cud_resp
    - X-Trans-Id: X-Trans-Id
 
 
@@ -379,9 +415,8 @@ Request
    - account: account
    - container: container
    - X-Auth-Token: X-Auth-Token
+   - X-Service-Token: X-Service-Token
    - X-Newest: X-Newest
-   - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key
-   - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2
    - X-Trans-Id-Extra: X-Trans-Id-Extra
 
 
@@ -390,28 +425,29 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - X-Container-Sync-Key: X-Container-Sync-Key
    - X-Container-Meta-name: X-Container-Meta-name
-   - Content-Length: Content-Length
+   - Content-Length: Content-Length_cud_resp
    - X-Container-Object-Count: X-Container-Object-Count
-   - X-Container-Write: X-Container-Write
+   - X-Container-Bytes-Used: X-Container-Bytes-Used
+   - X-Container-Write: X-Container-Write_resp
+   - X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes
    - X-Container-Meta-Quota-Count: X-Container-Meta-Quota-Count
    - Accept-Ranges: Accept-Ranges
-   - X-Container-Read: X-Container-Read
+   - X-Container-Read: X-Container-Read_resp
    - X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers
    - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key
-   - X-Container-Bytes-Used: X-Container-Bytes-Used
    - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2
    - X-Timestamp: X-Timestamp
    - X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin
    - X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age
+   - X-Container-Sync-Key: X-Container-Sync-Key_resp
+   - X-Container-Sync-To: X-Container-Sync-To_resp
    - Date: Date
    - X-Trans-Id: X-Trans-Id
-   - X-Container-Sync-To: X-Container-Sync-To
-   - Content-Type: Content-Type
-   - X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes
-   - X-Versions-Location: X-Versions-Location
-   - X-Versions-Mode: X-Versions-Mode
+   - Content-Type: Content-Type_cud_resp
+   - X-Versions-Location: X-Versions-Location_resp
+   - X-Versions-Mode: X-Versions-Mode_resp
+   - X-Storage-Policy: X-Storage-Policy
 
 
 
@@ -483,8 +519,7 @@ Request
    - account: account
    - container: container
    - X-Auth-Token: X-Auth-Token
-   - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key
-   - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2
+   - X-Service-Token: X-Service-Token
    - X-Trans-Id-Extra: X-Trans-Id-Extra
 
 
@@ -495,8 +530,8 @@ Response Parameters
 
    - Date: Date
    - X-Timestamp: X-Timestamp
-   - Content-Length: Content-Length
-   - Content-Type: Content-Type
+   - Content-Length: Content-Length_cud_resp
+   - Content-Type: Content-Type_cud_resp
    - X-Trans-Id: X-Trans-Id
 
 
diff --git a/api-ref/source/storage-object-services.inc b/api-ref/source/storage-object-services.inc
index d9ce9b3b8..5db102016 100644
--- a/api-ref/source/storage-object-services.inc
+++ b/api-ref/source/storage-object-services.inc
@@ -6,7 +6,11 @@ Objects
 
 Creates, replaces, shows details for, and deletes objects. Copies
 objects from another object with a new or different name. Updates
-object metadata.
+object metadata. For more information and concepts about
+objects see `Object Storage API overview
+<http://docs.openstack.org/developer/swift/api/object_api_v1_overview.html>`_
+and `Large Objects
+<http://docs.openstack.org/developer/swift/api/large_objects.html>`_.
 
 
 Get object content and metadata
@@ -96,9 +100,10 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - account: account
-   - object: object
    - container: container
+   - object: object
    - X-Auth-Token: X-Auth-Token
+   - X-Service-Token: X-Service-Token
    - X-Newest: X-Newest
    - temp_url_sig: temp_url_sig
    - temp_url_expires: temp_url_expires
@@ -117,20 +122,20 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - Content-Length: Content-Length
-   - X-Object-Meta-name: X-Object-Meta-name
-   - Content-Disposition: Content-Disposition
-   - Content-Encoding: Content-Encoding
+   - Content-Length: Content-Length_get_resp
+   - Content-Type: Content-Type_obj_resp
+   - X-Object-Meta-name: X-Object-Meta-name_resp
+   - Content-Disposition: Content-Disposition_resp
+   - Content-Encoding: Content-Encoding_resp
    - X-Delete-At: X-Delete-At
    - Accept-Ranges: Accept-Ranges
-   - X-Object-Manifest: X-Object-Manifest
+   - X-Object-Manifest: X-Object-Manifest_resp
    - Last-Modified: Last-Modified
-   - ETag: ETag
+   - ETag: ETag_obj_resp
    - X-Timestamp: X-Timestamp
    - X-Trans-Id: X-Trans-Id
    - Date: Date
    - X-Static-Large-Object: X-Static-Large-Object
-   - Content-Type: Content-Type
 
 
 
@@ -157,6 +162,16 @@ is a normal object and not a copy of the manifest. Instead it is a
 concatenation of all the segment objects. This means that you
 cannot copy objects larger than 5 GB.
 
+To create custom metadata, use the
+``X-Object-Meta-name`` header, where ``name`` is the name of the metadata
+item.
+
+Metadata keys (the name of the metadata) must be treated as case-insensitive
+at all times. These keys can contain ASCII 7-bit characters that are not
+control (0-31) characters, DEL, or a separator character, according to
+`HTTP/1.1 <http://www.w3.org/Protocols/rfc2616/rfc2616.html>`_ .
+The underscore character is silently converted to a hyphen.
+
 Example requests and responses:
 
 - Create object:
@@ -220,20 +235,20 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - account: account
-   - object: object
    - container: container
-   - multipart-manifest: multipart-manifest
+   - object: object
+   - multipart-manifest: multipart-manifest_put
    - temp_url_sig: temp_url_sig
    - temp_url_expires: temp_url_expires
-   - filename: filename
    - X-Object-Manifest: X-Object-Manifest
    - X-Auth-Token: X-Auth-Token
-   - Content-Length: Content-Length
+   - X-Service-Token: X-Service-Token
+   - Content-Length: Content-Length_put_req
    - Transfer-Encoding: Transfer-Encoding
-   - Content-Type: Content-Type
+   - Content-Type: Content-Type_obj_cu_req
    - X-Detect-Content-Type: X-Detect-Content-Type
    - X-Copy-From: X-Copy-From
-   - ETag: ETag
+   - ETag: ETag_obj_req
    - Content-Disposition: Content-Disposition
    - Content-Encoding: Content-Encoding
    - X-Delete-At: X-Delete-At
@@ -248,12 +263,12 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - Content-Length: Content-Length
-   - ETag: ETag
+   - Content-Length: Content-Length_cud_resp
+   - ETag: ETag_obj_received
    - X-Timestamp: X-Timestamp
    - X-Trans-Id: X-Trans-Id
    - Date: Date
-   - Content-Type: Content-Type
+   - Content-Type: Content-Type_obj_resp
    - last_modified: last_modified
 
 
@@ -272,25 +287,33 @@ Copies an object to another object in the object store.
 
 You can copy an object to a new object with the same name. Copying
 to the same name is an alternative to using POST to add metadata to
-an object. With POST , you must specify all the metadata. With COPY
-, you can add additional metadata to the object.
+an object. With POST, you must specify all the metadata. With COPY,
+you can add additional metadata to the object.
 
-With COPY , you can set the ``X-Fresh-Metadata`` header to ``true``
+With COPY, you can set the ``X-Fresh-Metadata`` header to ``true``
 to copy the object without any existing metadata.
 
 Alternatively, you can use PUT with the ``X-Copy-From`` request
 header to accomplish the same operation as the COPY object
 operation.
 
-The PUT operation always creates an object. If you use this
+The COPY operation always creates an object. If you use this
 operation on an existing object, you replace the existing object
 and metadata rather than modifying the object. Consequently, this
 operation returns the ``Created (201)`` response code.
 
-If you use this operation to copy a manifest object, the new object
+Normally, if you use this operation to copy a manifest object, the new object
 is a normal object and not a copy of the manifest. Instead it is a
 concatenation of all the segment objects. This means that you
-cannot copy objects larger than 5 GB in size. All metadata is
+cannot copy objects larger than 5 GB in size.
+
+To copy the manifest object, you include the
+``multipart-manifest=get`` query string in the COPY request.
+The new object contains the same manifest as the original.
+The segment objects are not copied. Instead, both the original
+and new manifest objects share the same set of segment objects.
+
+All metadata is
 preserved during the object copy. If you specify metadata on the
 request to copy the object, either PUT or COPY , the metadata
 overwrites any conflicting keys on the target (new) object.
@@ -360,11 +383,14 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - account: account
-   - object: object
    - container: container
+   - object: object
+   - multipart-manifest: multipart-manifest_copy
    - X-Auth-Token: X-Auth-Token
+   - X-Service-Token: X-Service-Token
    - Destination: Destination
-   - Content-Type: Content-Type
+   - Destination-Account: Destination-Account
+   - Content-Type: Content-Type_obj_cu_req
    - Content-Encoding: Content-Encoding
    - Content-Disposition: Content-Disposition
    - X-Object-Meta-name: X-Object-Meta-name
@@ -377,16 +403,16 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - Content-Length: Content-Length
-   - X-Object-Meta-name: X-Object-Meta-name
+   - Content-Length: Content-Length_cud_resp
    - X-Copied-From-Last-Modified: X-Copied-From-Last-Modified
    - X-Copied-From: X-Copied-From
+   - X-Copied-From-Account: X-Copied-From-Account
    - Last-Modified: Last-Modified
-   - ETag: ETag
+   - ETag: ETag_obj_copied
    - X-Timestamp: X-Timestamp
    - X-Trans-Id: X-Trans-Id
    - Date: Date
-   - Content-Type: Content-Type
+   - Content-Type: Content-Type_obj_resp
 
 
 
@@ -399,18 +425,18 @@ Delete object
 
 Permanently deletes an object from the object store.
 
-You can use the COPY method to copy the object to a new location.
-Then, use the DELETE method to delete the original object.
-
 Object deletion occurs immediately at request time. Any subsequent
-GET , HEAD , POST , or DELETE operations return a ``404 Not Found``
+GET, HEAD, POST, or DELETE operations will return a ``404 Not Found``
 error code.
 
 For static large object manifests, you can add the ``?multipart-
 manifest=delete`` query parameter. This operation deletes the
-segment objects and if all deletions succeed, this operation
+segment objects and, if all deletions succeed, this operation
 deletes the manifest object.
 
+An alternative to using the DELETE operation is to use
+the POST operation with the ``bulk-delete`` query parameter.
+
 Example request and response:
 
 - Delete the ``helloworld`` object from the ``marktwain`` container:
@@ -445,10 +471,11 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - account: account
-   - object: object
    - container: container
-   - multipart-manifest: multipart-manifest
+   - object: object
+   - multipart-manifest: multipart-manifest_delete
    - X-Auth-Token: X-Auth-Token
+   - X-Service-Token: X-Service-Token
    - X-Trans-Id-Extra: X-Trans-Id-Extra
 
 
@@ -459,8 +486,8 @@ Response Parameters
 
    - Date: Date
    - X-Timestamp: X-Timestamp
-   - Content-Length: Content-Length
-   - Content-Type: Content-Type
+   - Content-Length: Content-Length_cud_resp
+   - Content-Type: Content-Type_cud_resp
    - X-Trans-Id: X-Trans-Id
 
 
@@ -474,10 +501,7 @@ Show object metadata
 
 Shows object metadata.
 
-If the ``Content-Length`` response header is non-zero, the example
-cURL command stalls after it prints the response headers because it
-is waiting for a response body. However, the Object Storage system
-does not return a response body for the HEAD operation.
+
 
 Example requests and responses:
 
@@ -485,7 +509,7 @@ Example requests and responses:
 
   ::
 
-     curl -i $publicURL/marktwain/goodbye -X HEAD -H "X-Auth-Token: $token"
+     curl $publicURL/marktwain/goodbye --head -H "X-Auth-Token: $token"
 
 
 
@@ -503,6 +527,12 @@ Example requests and responses:
      X-Trans-Id: tx37ea34dcd1ed48ca9bc7d-0052d84b6f
      Date: Thu, 16 Jan 2014 21:13:19 GMT
 
+  Note: The ``--head`` option was used in the above example. If we had
+  used ``-i -X HEAD`` and the ``Content-Length`` response header is non-zero,
+  the cURL command stalls after it prints the response headers because it
+  is waiting for a response body. However, the Object Storage system
+  does not return a response body for the HEAD operation.
+
 
 If the request succeeds, the operation returns the ``200`` response
 code.
@@ -518,9 +548,10 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - account: account
-   - object: object
    - container: container
+   - object: object
    - X-Auth-Token: X-Auth-Token
+   - X-Service-Token: X-Service-Token
    - temp_url_sig: temp_url_sig
    - temp_url_expires: temp_url_expires
    - filename: filename
@@ -534,20 +565,19 @@ Response Parameters
 
 .. rest_parameters:: parameters.yaml
 
-   - Last-Modified: Last-Modified
-   - Content-Length: Content-Length
+   - Content-Length: Content-Length_obj_head_resp
    - X-Object-Meta-name: X-Object-Meta-name
-   - Content-Disposition: Content-Disposition
-   - Content-Encoding: Content-Encoding
+   - Content-Disposition: Content-Disposition_resp
+   - Content-Encoding: Content-Encoding_resp
    - X-Delete-At: X-Delete-At
-   - X-Object-Manifest: X-Object-Manifest
+   - X-Object-Manifest: X-Object-Manifest_resp
    - Last-Modified: Last-Modified
-   - ETag: ETag
+   - ETag: ETag_obj_resp
    - X-Timestamp: X-Timestamp
    - X-Trans-Id: X-Trans-Id
    - Date: Date
    - X-Static-Large-Object: X-Static-Large-Object
-   - Content-Type: Content-Type
+   - Content-Type: Content-Type_obj_resp
 
 
 
@@ -565,20 +595,25 @@ Create or update object metadata
 
 Creates or updates object metadata.
 
-To create or update custom metadata, use the ``X-Object-
-Meta-{name}`` header, where ``{name}`` is the name of the metadata
+To create or update custom metadata, use the
+``X-Object-Meta-name`` header, where ``name`` is the name of the metadata
 item.
 
-In addition to the custom metadata, you can update the ``Content-
-Type``, ``Content-Encoding``, ``Content-Disposition``, and ``X
--Delete-At`` system metadata items. However you cannot update other
+Metadata keys (the name of the metadata) must be treated as case-insensitive
+at all times. These keys can contain ASCII 7-bit characters that are not
+control (0-31) characters, DEL, or a separator character, according to
+`HTTP/1.1 <http://www.w3.org/Protocols/rfc2616/rfc2616.html>`_ .
+The underscore character is silently converted to a hyphen.
+
+In addition to the custom metadata, you can update the
+``Content-Type``, ``Content-Encoding``, ``Content-Disposition``, and
+``X-Delete-At`` system metadata items. However you cannot update other
 system metadata, such as ``Content-Length`` or ``Last-Modified``.
 
 You can use COPY as an alternate to the POST operation by copying
 to the same object. With the POST operation you must specify all
 metadata items, whereas with the COPY operation, you need to
 specify only changed or additional items.
-
 All metadata is preserved during the object copy. If you specify
 metadata on the request to copy the object, either PUT or COPY ,
 the metadata overwrites any conflicting keys on the target (new)
@@ -595,11 +630,19 @@ to define when to expire the object.
 
 When used as described in this section, the POST operation creates
 or replaces metadata. This form of the operation has no request
-body.
+body. There are alternate uses of the POST operation as follows:
+
+- You can also use the `form POST feature
+  <http://docs.openstack.org/liberty/config-reference/content/object-
+  storage-form-post.html>`_ to upload objects.
 
-You can also use the `form POST feature
-<http://docs.openstack.org/liberty/config-reference/content/object-
-storage-form-post.html>`_ to upload objects.
+- The POST operation when used with the ``bulk-delete`` query parameter
+  can be used to delete multiple objects and containers in a single
+  operation.
+
+- The POST operation when used with the ``extract-archive`` query parameter
+  can be used to upload an archive (tar file). The archive is then extracted
+  to create objects.
 
 Example requests and responses:
 
@@ -659,16 +702,18 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - account: account
-   - object: object
    - container: container
+   - object: object
+   - bulk-delete: bulk-delete
+   - extract-archive: extract-archive
    - X-Auth-Token: X-Auth-Token
+   - X-Service-Token: X-Service-Token
    - X-Object-Meta-name: X-Object-Meta-name
    - X-Delete-At: X-Delete-At
    - Content-Disposition: Content-Disposition
    - Content-Encoding: Content-Encoding
    - X-Delete-After: X-Delete-After
-   - Content-Type: Content-Type
-   - X-Detect-Content-Type: X-Detect-Content-Type
+   - Content-Type: Content-Type_obj_cu_req
    - X-Trans-Id-Extra: X-Trans-Id-Extra
 
 
@@ -679,8 +724,8 @@ Response Parameters
 
    - Date: Date
    - X-Timestamp: X-Timestamp
-   - Content-Length: Content-Length
-   - Content-Type: Content-Type
+   - Content-Length: Content-Length_cud_resp
+   - Content-Type: Content-Type_cud_resp
    - X-Trans-Id: X-Trans-Id
 
 
diff --git a/api-ref/source/storage_info.inc b/api-ref/source/storage_info.inc
index 60b4082f7..0487210b3 100644
--- a/api-ref/source/storage_info.inc
+++ b/api-ref/source/storage_info.inc
@@ -15,6 +15,11 @@ List activated capabilities
 
 Lists the activated capabilities for this version of the OpenStack Object Storage API.
 
+Most of the information is "public" i.e. visible to all callers. However, some
+configuration and capability items are reserved for the administrators of the
+system. To access this data, the ``swiftinfo_sig`` and ``swiftinfo_expires``
+query parameters must be added to the request.
+
 
 Normal response codes: 200
 Error response codes: