Revision a8326bef docs/source/devguide.rst
| b/docs/source/devguide.rst | ||
|---|---|---|
| 25 | 25 |
========================= ================================ |
| 26 | 26 |
Revision Description |
| 27 | 27 |
========================= ================================ |
| 28 |
0.5 (July 21, 2011) Object update from another object's data.
|
|
| 28 |
0.5 (July 22, 2011) Object update from another object's data.
|
|
| 29 | 29 |
\ Support object truncate. |
| 30 | 30 |
\ Create object using a standard HTML form. |
| 31 | 31 |
\ Purge container/object history. |
| 32 | 32 |
\ List other accounts that share objects with a user. |
| 33 | 33 |
\ List shared containers/objects. |
| 34 | 34 |
\ Update implementation guidelines. |
| 35 |
\ Check preconditions when creating/updating objects. |
|
| 35 | 36 |
0.4 (July 01, 2011) Object permissions and account groups. |
| 36 | 37 |
\ Control versioning behavior and container quotas with container policy directives. |
| 37 | 38 |
\ Support updating/deleting individual metadata with ``POST``. |
| ... | ... | |
| 159 | 160 |
HEAD |
| 160 | 161 |
"""" |
| 161 | 162 |
|
| 163 |
==================== =========================== |
|
| 164 |
Request Header Name Value |
|
| 165 |
==================== =========================== |
|
| 166 |
If-Modified-Since Retrieve if account has changed since provided timestamp |
|
| 167 |
If-Unmodified-Since Retrieve if account has not changed since provided timestamp |
|
| 168 |
==================== =========================== |
|
| 169 |
|
|
| 170 |
| |
|
| 171 |
|
|
| 162 | 172 |
====================== =================================== |
| 163 | 173 |
Request Parameter Name Value |
| 164 | 174 |
====================== =================================== |
| ... | ... | |
| 247 | 257 |
POST |
| 248 | 258 |
"""" |
| 249 | 259 |
|
| 250 |
====================== ============================================ |
|
| 251 |
Request Parameter Name Value |
|
| 252 |
====================== ============================================ |
|
| 253 |
update Do not replace metadata/groups (no value parameter) |
|
| 254 |
====================== ============================================ |
|
| 255 |
|
|
| 256 |
| |
|
| 257 |
|
|
| 258 | 260 |
==================== =========================== |
| 259 | 261 |
Request Header Name Value |
| 260 | 262 |
==================== =========================== |
| ... | ... | |
| 262 | 264 |
X-Account-Meta-* Optional user defined metadata |
| 263 | 265 |
==================== =========================== |
| 264 | 266 |
|
| 267 |
| |
|
| 268 |
|
|
| 269 |
====================== ============================================ |
|
| 270 |
Request Parameter Name Value |
|
| 271 |
====================== ============================================ |
|
| 272 |
update Do not replace metadata/groups (no value parameter) |
|
| 273 |
====================== ============================================ |
|
| 274 |
|
|
| 265 | 275 |
No reply content/headers. |
| 266 | 276 |
|
| 267 | 277 |
The operation will overwrite all user defined metadata, except if ``update`` is defined. |
| ... | ... | |
| 293 | 303 |
HEAD |
| 294 | 304 |
"""" |
| 295 | 305 |
|
| 306 |
==================== =========================== |
|
| 307 |
Request Header Name Value |
|
| 308 |
==================== =========================== |
|
| 309 |
If-Modified-Since Retrieve if container has changed since provided timestamp |
|
| 310 |
If-Unmodified-Since Retrieve if container has not changed since provided timestamp |
|
| 311 |
==================== =========================== |
|
| 312 |
|
|
| 313 |
| |
|
| 314 |
|
|
| 296 | 315 |
====================== =================================== |
| 297 | 316 |
Request Parameter Name Value |
| 298 | 317 |
====================== =================================== |
| ... | ... | |
| 437 | 456 |
POST |
| 438 | 457 |
"""" |
| 439 | 458 |
|
| 440 |
====================== ============================================ |
|
| 441 |
Request Parameter Name Value |
|
| 442 |
====================== ============================================ |
|
| 443 |
update Do not replace metadata/policy (no value parameter) |
|
| 444 |
====================== ============================================ |
|
| 445 |
|
|
| 446 |
| |
|
| 447 |
|
|
| 448 | 459 |
==================== ================================ |
| 449 | 460 |
Request Header Name Value |
| 450 | 461 |
==================== ================================ |
| ... | ... | |
| 452 | 463 |
X-Container-Meta-* Optional user defined metadata |
| 453 | 464 |
==================== ================================ |
| 454 | 465 |
|
| 466 |
| |
|
| 467 |
|
|
| 468 |
====================== ============================================ |
|
| 469 |
Request Parameter Name Value |
|
| 470 |
====================== ============================================ |
|
| 471 |
update Do not replace metadata/policy (no value parameter) |
|
| 472 |
====================== ============================================ |
|
| 473 |
|
|
| 455 | 474 |
No reply content/headers. |
| 456 | 475 |
|
| 457 | 476 |
The operation will overwrite all user defined metadata, except if ``update`` is defined. |
| ... | ... | |
| 506 | 525 |
HEAD |
| 507 | 526 |
"""" |
| 508 | 527 |
|
| 528 |
==================== ================================ |
|
| 529 |
Request Header Name Value |
|
| 530 |
==================== ================================ |
|
| 531 |
If-Match Retrieve if ETags match |
|
| 532 |
If-None-Match Retrieve if ETags don't match |
|
| 533 |
If-Modified-Since Retrieve if object has changed since provided timestamp |
|
| 534 |
If-Unmodified-Since Retrieve if object has not changed since provided timestamp |
|
| 535 |
==================== ================================ |
|
| 536 |
|
|
| 537 |
| |
|
| 538 |
|
|
| 509 | 539 |
====================== =================================== |
| 510 | 540 |
Request Parameter Name Value |
| 511 | 541 |
====================== =================================== |
| ... | ... | |
| 645 | 675 |
==================== ================================ |
| 646 | 676 |
Request Header Name Value |
| 647 | 677 |
==================== ================================ |
| 678 |
If-Match Put if ETags match with current object |
|
| 679 |
If-None-Match Put if ETags don't match with current object |
|
| 648 | 680 |
ETag The MD5 hash of the object (optional to check written data) |
| 649 | 681 |
Content-Length The size of the data written |
| 650 | 682 |
Content-Type The MIME content type of the object |
| ... | ... | |
| 712 | 744 |
==================== ================================ |
| 713 | 745 |
Request Header Name Value |
| 714 | 746 |
==================== ================================ |
| 747 |
If-Match Proceed if ETags match with object |
|
| 748 |
If-None-Match Proceed if ETags don't match with object |
|
| 715 | 749 |
Destination The destination path in the form ``/<container>/<object>`` |
| 716 | 750 |
Content-Type The MIME content type of the object (optional) |
| 717 | 751 |
Content-Encoding The encoding of the object (optional) |
| ... | ... | |
| 744 | 778 |
POST |
| 745 | 779 |
"""" |
| 746 | 780 |
|
| 747 |
====================== ============================================ |
|
| 748 |
Request Parameter Name Value |
|
| 749 |
====================== ============================================ |
|
| 750 |
update Do not replace metadata (no value parameter) |
|
| 751 |
====================== ============================================ |
|
| 752 |
|
|
| 753 |
| |
|
| 754 |
|
|
| 755 | 781 |
==================== ================================ |
| 756 | 782 |
Request Header Name Value |
| 757 | 783 |
==================== ================================ |
| 784 |
If-Match Proceed if ETags match with object |
|
| 785 |
If-None-Match Proceed if ETags don't match with object |
|
| 758 | 786 |
Content-Length The size of the data written (optional, to update) |
| 759 | 787 |
Content-Type The MIME content type of the object (optional, to update) |
| 760 | 788 |
Content-Range The range of data supplied (optional, to update) |
| ... | ... | |
| 770 | 798 |
X-Object-Meta-* Optional user defined metadata |
| 771 | 799 |
==================== ================================ |
| 772 | 800 |
|
| 801 |
| |
|
| 802 |
|
|
| 803 |
====================== ============================================ |
|
| 804 |
Request Parameter Name Value |
|
| 805 |
====================== ============================================ |
|
| 806 |
update Do not replace metadata (no value parameter) |
|
| 807 |
====================== ============================================ |
|
| 808 |
|
|
| 773 | 809 |
The ``Content-Encoding``, ``Content-Disposition``, ``X-Object-Manifest`` and ``X-Object-Meta-*`` headers are considered to be user defined metadata. An operation without the ``update`` parameter will overwrite all previous values and remove any keys not supplied. When using ``update`` any metadata with an empty value will be deleted. |
| 774 | 810 |
|
| 775 | 811 |
To change permissions, include an ``X-Object-Sharing`` header (as defined in ``PUT``). To publish, include an ``X-Object-Public`` header, with a value of ``true``. If no such headers are defined, no changes will be applied to sharing/public. Use empty values to remove permissions/unpublish (unpublishing also works with ``false`` as a header value). Sharing options are applied to the object - not its versions. |
| ... | ... | |
| 886 | 922 |
* Container policies to manage behavior and limits. |
| 887 | 923 |
* Headers ``X-Container-Block-*`` at the container level, exposing the underlying storage characteristics. |
| 888 | 924 |
* All metadata replies, at all levels, include latest modification information. |
| 889 |
* At all levels, a ``GET`` request may use ``If-Modified-Since`` and ``If-Unmodified-Since`` headers. |
|
| 925 |
* At all levels, a ``HEAD`` or ``GET`` request may use ``If-Modified-Since`` and ``If-Unmodified-Since`` headers.
|
|
| 890 | 926 |
* Container/object lists include all associated metadata if the reply is of type json/xml. Some names are kept to their OOS API equivalents for compatibility. |
| 891 | 927 |
* Option to include only shared containers/objects in listings. |
| 892 | 928 |
* Object metadata allowed, in addition to ``X-Object-Meta-*``: ``Content-Encoding``, ``Content-Disposition``, ``X-Object-Manifest``. These are all replaced with every update operation, except if using the ``update`` parameter (in which case individual keys can also be deleted). Deleting meta by providing empty values also works when copying/moving an object. |
| ... | ... | |
| 896 | 932 |
* Object create using ``POST`` to support standard HTML forms. |
| 897 | 933 |
* Partial object updates through ``POST``, using the ``Content-Length``, ``Content-Type``, ``Content-Range`` and ``Transfer-Encoding`` headers. Use another object's data to update with ``X-Source-Object`` and ``X-Source-Version``. Truncate with ``X-Object-Bytes``. |
| 898 | 934 |
* Object ``MOVE`` support. |
| 935 |
* Conditional object create/update operations, using ``If-Match`` and ``If-None-Match`` headers. |
|
| 899 | 936 |
* Time-variant account/container listings via the ``until`` parameter. |
| 900 | 937 |
* Object versions - parameter ``version`` in ``HEAD``/``GET`` (list versions with ``GET``), ``X-Object-Version-*`` meta in replies, ``X-Source-Version`` in ``PUT``/``COPY``. |
| 901 | 938 |
* Sharing/publishing with ``X-Object-Sharing``, ``X-Object-Public`` at the object level. Cross-user operations are allowed - controlled by sharing directives. Permissions may include groups defined with ``X-Account-Group-*`` at the account level. These apply to the object - not its versions. |
| ... | ... | |
| 948 | 985 |
Implementation Guidelines |
| 949 | 986 |
^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 950 | 987 |
|
| 951 |
Pithos clients should use the ``pithos`` and ``trash`` containers for active and inactive objects respectively. If any of these containers is not found, the client software should create it, without interrupting the user's workflow. The ``home`` element corresponds to ``pithos`` and the ``trash`` element to ``trash``. Use ``PUT`` with the ``X-Move-From`` header, or ``MOVE`` to transfer objects from one container to the other. Use ``DELETE`` to remove from ``pithos`` without trashing, or to remove from ``trash``. When moving objects, detect naming conflicts with the ``If-Match`` or ``If-None-Match`` headers (**TBD**). Such conflicts should be resolved by the user.
|
|
| 988 |
Pithos clients should use the ``pithos`` and ``trash`` containers for active and inactive objects respectively. If any of these containers is not found, the client software should create it, without interrupting the user's workflow. The ``home`` element corresponds to ``pithos`` and the ``trash`` element to ``trash``. Use ``PUT`` with the ``X-Move-From`` header, or ``MOVE`` to transfer objects from one container to the other. Use ``DELETE`` to remove from ``pithos`` without trashing, or to remove from ``trash``. When moving objects, detect naming conflicts with the ``If-Match`` or ``If-None-Match`` headers. Such conflicts should be resolved by the user. |
|
| 952 | 989 |
|
| 953 | 990 |
Object names should use the ``/`` delimiter to impose a hierarchy of folders and files. |
| 954 | 991 |
|
Also available in: Unified diff