Revision a6eb13e9 docs/source/devguide.rst
| b/docs/source/devguide.rst | ||
|---|---|---|
| 25 | 25 |
========================= ================================ |
| 26 | 26 |
Revision Description |
| 27 | 27 |
========================= ================================ |
| 28 |
0.4 (June 22, 2011) Support updating/deleting individual metadata with ``POST``. |
|
| 28 | 29 |
0.3 (June 14, 2011) Large object support with ``X-Object-Manifest``. |
| 29 | 30 |
\ Allow for publicly available objects via ``https://hostname/public``. |
| 30 | 31 |
\ Support time-variant account/container listings. |
| 31 |
\ Add source version when duplicating with PUT/COPY/MOVE.
|
|
| 32 |
\ Add source version when duplicating with PUT/COPY. |
|
| 32 | 33 |
\ Request version in object HEAD/GET requests (list versions with GET). |
| 33 | 34 |
0.2 (May 31, 2011) Add object meta listing and filtering in containers. |
| 34 | 35 |
\ Include underlying storage characteristics in container meta. |
| ... | ... | |
| 183 | 184 |
POST |
| 184 | 185 |
"""" |
| 185 | 186 |
|
| 187 |
====================== ============================================ |
|
| 188 |
Request Parameter Name Value |
|
| 189 |
====================== ============================================ |
|
| 190 |
update Do not replace metadata (no value parameter) |
|
| 191 |
====================== ============================================ |
|
| 192 |
|
|
| 193 |
| |
|
| 194 |
|
|
| 186 | 195 |
==================== =========================== |
| 187 | 196 |
Request Header Name Value |
| 188 | 197 |
==================== =========================== |
| ... | ... | |
| 191 | 200 |
|
| 192 | 201 |
No reply content/headers. |
| 193 | 202 |
|
| 194 |
The update operation will overwrite all user defined metadata.
|
|
| 203 |
The operation will overwrite all user defined metadata, except if ``update`` is defined.
|
|
| 195 | 204 |
|
| 196 | 205 |
================ =============================== |
| 197 | 206 |
Return Code Description |
| ... | ... | |
| 340 | 349 |
POST |
| 341 | 350 |
"""" |
| 342 | 351 |
|
| 352 |
====================== ============================================ |
|
| 353 |
Request Parameter Name Value |
|
| 354 |
====================== ============================================ |
|
| 355 |
update Do not replace metadata (no value parameter) |
|
| 356 |
====================== ============================================ |
|
| 357 |
|
|
| 358 |
| |
|
| 359 |
|
|
| 343 | 360 |
==================== ================================ |
| 344 | 361 |
Request Header Name Value |
| 345 | 362 |
==================== ================================ |
| ... | ... | |
| 348 | 365 |
|
| 349 | 366 |
No reply content/headers. |
| 350 | 367 |
|
| 351 |
The update operation will overwrite all user defined metadata.
|
|
| 368 |
The operation will overwrite all user defined metadata, except if ``update`` is defined.
|
|
| 352 | 369 |
|
| 353 | 370 |
================ =============================== |
| 354 | 371 |
Return Code Description |
| ... | ... | |
| 574 | 591 |
X-Object-Meta-* Optional user defined metadata |
| 575 | 592 |
==================== ================================ |
| 576 | 593 |
|
| 594 |
Refer to ``POST`` for a description of request headers. Metadata is also copied, updated with any values defined. |
|
| 595 |
|
|
| 577 | 596 |
No reply content/headers. |
| 578 | 597 |
|
| 579 | 598 |
=========================== ============================== |
| ... | ... | |
| 592 | 611 |
POST |
| 593 | 612 |
"""" |
| 594 | 613 |
|
| 614 |
====================== ============================================ |
|
| 615 |
Request Parameter Name Value |
|
| 616 |
====================== ============================================ |
|
| 617 |
update Do not replace metadata (no value parameter) |
|
| 618 |
====================== ============================================ |
|
| 619 |
|
|
| 620 |
| |
|
| 621 |
|
|
| 595 | 622 |
==================== ================================ |
| 596 | 623 |
Request Header Name Value |
| 597 | 624 |
==================== ================================ |
| ... | ... | |
| 606 | 633 |
X-Object-Meta-* Optional user defined metadata |
| 607 | 634 |
==================== ================================ |
| 608 | 635 |
|
| 609 |
The ``Content-Encoding``, ``Content-Disposition``, ``X-Object-Manifest``, ``X-Object-Public`` (**TBD**) and ``X-Object-Meta-*`` headers are considered to be user defined metadata. The update operation will overwrite all previous values and remove any keys not supplied.
|
|
| 636 |
The ``Content-Encoding``, ``Content-Disposition``, ``X-Object-Manifest``, ``X-Object-Public`` (**TBD**) 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.
|
|
| 610 | 637 |
|
| 611 |
To update an object: |
|
| 638 |
To update an object's data:
|
|
| 612 | 639 |
|
| 640 |
* Set ``Content-Type`` to ``application/octet-stream``. If ``Content-Type`` has some other value, it will be ignored and only the metadata will be updated. |
|
| 613 | 641 |
* Supply ``Content-Length`` (except if using chunked transfers), ``Content-Type`` and ``Content-Range`` headers. |
| 614 |
* Set ``Content-Type`` to ``application/octet-stream``. |
|
| 615 | 642 |
* Set ``Content-Range`` as specified in RFC2616, with the following differences: |
| 616 | 643 |
|
| 617 | 644 |
* Client software MAY omit ``last-byte-pos`` of if the length of the range being transferred is unknown or difficult to determine. |
| ... | ... | |
| 636 | 663 |
202 (Accepted) The request has been accepted (not a data update) |
| 637 | 664 |
204 (No Content) The request succeeded (data updated) |
| 638 | 665 |
411 (Length Required) Missing ``Content-Length`` in the request |
| 639 |
416 (Range Not Satisfiable) The supplied range is out of limits or invalid size
|
|
| 666 |
416 (Range Not Satisfiable) The supplied range is invalid
|
|
| 640 | 667 |
=========================== ============================== |
| 641 | 668 |
|
| 642 | 669 |
|
| ... | ... | |
| 682 | 709 |
* All metadata replies, at all levels, include latest modification information. |
| 683 | 710 |
* At all levels, a ``GET`` request may use ``If-Modified-Since`` and ``If-Unmodified-Since`` headers. |
| 684 | 711 |
* 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. |
| 685 |
* Object metadata allowed, in addition to ``X-Object-Meta-*``: ``Content-Encoding``, ``Content-Disposition``, ``X-Object-Manifest``, ``X-Object-Public`` (**TBD**). These are all replaced with every update operation. |
|
| 712 |
* Object metadata allowed, in addition to ``X-Object-Meta-*``: ``Content-Encoding``, ``Content-Disposition``, ``X-Object-Manifest``, ``X-Object-Public`` (**TBD**). 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.
|
|
| 686 | 713 |
* Multi-range object GET support as outlined in RFC2616. |
| 687 | 714 |
* Object hashmap retrieval through GET and the ``format`` parameter. |
| 688 | 715 |
* Partial object updates through POST, using the ``Content-Length``, ``Content-Type``, ``Content-Range`` and ``Transfer-Encoding`` headers. |
| ... | ... | |
| 702 | 729 |
* Container/object lists use a ``200`` return code if the reply is of type json/xml. The reply will include an empty json/xml. |
| 703 | 730 |
* In headers, dates are formatted according to RFC 1123. In extended information listings, dates are formatted according to ISO 8601. |
| 704 | 731 |
* The ``Last-Modified`` header value always reflects the actual latest change timestamp, regardless of time control parameters and version requests. Time precondition checks with ``If-Modified-Since`` and ``If-Unmodified-Since`` headers are applied to this value. |
| 732 |
* A copy/move using ``PUT``/``COPY``/``MOVE`` will always update metadata, keeping all old values except the ones redefined in the request headers. |
|
| 705 | 733 |
* A ``HEAD`` or ``GET`` for an ``X-Object-Manifest`` object, will include modified ``Content-Length`` and ``ETag`` headers, according to the characteristics of the objects under the specified prefix. The ``Etag`` will be the MD5 hash of the corresponding ETags concatenated. In extended container listings there is no metadata processing. |
| 706 | 734 |
|
| 707 | 735 |
The Pithos Client |
| ... | ... | |
| 796 | 824 |
-H "X-Auth-Token: 0000" \ |
| 797 | 825 |
https://pithos.dev.grnet.gr/v1/user/pithos?format=json |
| 798 | 826 |
|
| 827 |
It is recommended that extended replies are cached and subsequent requests utilize the ``If-Modified-Since`` header. |
|
| 828 |
|
|
| 799 | 829 |
* List metadata keys used by objects in a container |
| 800 | 830 |
|
| 801 | 831 |
Will be in the ``X-Container-Object-Meta`` reply header, included in container information or object list (``HEAD`` or ``GET``). |
Also available in: Unified diff