Add x-newest header docs for openstack swift

[Chuck Thier]

When a GET or HEAD request is made to an object, the default behavior is to get the data from one of the replicas (could be any of them). The downside to this is that if there are older versions of the object (due to eventual consistency) it is possible to get an older version of the object. The upside is that the for the majority of use cases, this isn't an issue.

For the small subset of use cases that need to make sure that they get the latest version of the object, they can set the "X-Newest" header to "True". If this is set, the proxy server will check all replicas of the object and only return the newest object. The downside to this is that the request can take longer, since it has to contact all the replicas. It is also more expensive for the backend, so only recommended when it is absolutely needed.

--
Chuck

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/61090

[Diane Fleming (diane-fleming)]

Made changes in api-site wadl file also https://review.openstack.org/61256

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/61090
Committed: http://github.com/openstack/object-api/commit/7be42361ce73a87ecc28569cc0cb009856f077d3
Submitter: Jenkins
Branch: master

commit 7be42361ce73a87ecc28569cc0cb009856f077d3
Author: Fabien Boucher <email address hidden>
Date: Tue Dec 10 12:39:40 2013 +0100

    Add an explanation for X-Newest header

    Add a short explanation of the X-newest header
    in each section (account/container/object).

    Change-Id: I3a9ab126bf4fecf8d837d11850e09ef31f31ff7e
    Closes-Bug: #1193417

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/61256
Committed: https://git.openstack.org/cgit/openstack/api-site/commit/?id=171da5887805af0ac0101ed50518549dd5ab5b68
Submitter: Jenkins
Branch: master

commit 171da5887805af0ac0101ed50518549dd5ab5b68
Author: Diane Fleming <email address hidden>
Date: Tue Dec 10 16:22:31 2013 -0600

    Add note about x-newest header and update formatting and parameter position in WADL

    Partial-Bug: #1193417

    Change-Id: Id7fe495ff6a6ec326b9b1539fc6efe32f7bf0f49
    author: diane fleming