1 Pithos v2 Developer Guide
2 =========================
7 Pithos is a storage service implemented by GRNET (http://www.grnet.gr). Data is stored as objects, organized in containers, belonging to an account. This hierarchy of storage layers has been inspired by the OpenStack Object Storage (OOS) API and similar CloudFiles API by Rackspace. The Pithos API follows the OOS API as closely as possible. One of the design requirements has been to be able to use Pithos with clients built for the OOS, without changes.
9 However, to be able to take full advantage of the Pithos infrastructure, client software should be aware of the extensions that differentiate Pithos from OOS. Pithos objects can be updated, or appended to. Pithos will store sharing permissions per object and enforce corresponding authorization policies. Automatic version management, allows taking account and container listings back in time, as well as reading previous instances of objects.
11 The storage backend of Pithos is block oriented, permitting efficient, deduplicated data placement. The block structure of objects is exposed at the API layer, in order to encourage external software to implement advanced data management operations.
13 This document's goals are:
15 * Define the Pithos ReST API that allows the storage and retrieval of data and metadata via HTTP calls
16 * Specify metadata semantics and user interface guidelines for a common experience across client software implementations
18 The present document is meant to be read alongside the OOS API documentation. Thus, it is suggested that the reader is familiar with associated technologies, the OOS API as well as the first version of the Pithos API. This document refers to the second version of Pithos. Information on the first version of the storage API can be found at http://code.google.com/p/gss.
20 Whatever marked as to be determined (**TBD**), should not be considered by implementors.
25 ========================= ================================
27 ========================= ================================
28 0.6 (Sept 05, 2011) Reply with Merkle hash as the ETag when updating objects.
29 \ Include version id in object replace/change replies.
30 0.5 (July 22, 2011) Object update from another object's data.
31 \ Support object truncate.
32 \ Create object using a standard HTML form.
33 \ Purge container/object history.
34 \ List other accounts that share objects with a user.
35 \ List shared containers/objects.
36 \ Update implementation guidelines.
37 \ Check preconditions when creating/updating objects.
38 0.4 (July 01, 2011) Object permissions and account groups.
39 \ Control versioning behavior and container quotas with container policy directives.
40 \ Support updating/deleting individual metadata with ``POST``.
41 \ Create object using hashmap.
42 0.3 (June 14, 2011) Large object support with ``X-Object-Manifest``.
43 \ Allow for publicly available objects via ``https://hostname/public``.
44 \ Support time-variant account/container listings.
45 \ Add source version when duplicating with ``PUT``/``COPY``.
46 \ Request version in object ``HEAD``/``GET`` requests (list versions with ``GET``).
47 0.2 (May 31, 2011) Add object meta listing and filtering in containers.
48 \ Include underlying storage characteristics in container meta.
49 \ Support for partial object updates through ``POST``.
50 \ Expose object hashmaps through ``GET``.
51 \ Support for multi-range object ``GET`` requests.
52 0.1 (May 17, 2011) Initial release. Based on OpenStack Object Storage Developer Guide API v1 (Apr. 15, 2011).
53 ========================= ================================
58 The URI requests supported by the Pithos API follow one of the following forms:
60 * Top level: ``https://hostname/v1/``
61 * Account level: ``https://hostname/v1/<account>``
62 * Container level: ``https://hostname/v1/<account>/<container>``
63 * Object level: ``https://hostname/v1/<account>/<container>/<object>``
65 All requests must include an ``X-Auth-Token`` - as a header, or a parameter. The process of obtaining the token is still to be determined (**TBD**).
67 The allowable request operations and respective return codes per level are presented in the remainder of this chapter. Common to all requests are the following return codes.
69 ========================= ================================
70 Return Code Description
71 ========================= ================================
72 400 (Bad Request) The request is invalid
73 401 (Unauthorized) Request not allowed
74 404 (Not Found) The requested resource was not found
75 503 (Service Unavailable) The request cannot be completed because of an internal error
76 ========================= ================================
83 ========= ==================
85 ========= ==================
86 GET Authentication (for compatibility with the OOS API) or list allowed accounts
87 ========= ==================
92 If the ``X-Auth-User`` and ``X-Auth-Key`` headers are given, a dummy ``X-Auth-Token`` and ``X-Storage-Url`` will be replied, which can be used as a guest token/namespace for testing Pithos.
94 ================ =====================
95 Return Code Description
96 ================ =====================
97 204 (No Content) The request succeeded
98 ================ =====================
100 If an ``X-Auth-Token`` is already present, the operation will be interpreted as a request to list other accounts that share objects to the user.
102 ====================== =========================
103 Request Parameter Name Value
104 ====================== =========================
105 limit The amount of results requested (default is 10000)
106 marker Return containers with name lexicographically after marker
107 format Optional extended reply type (can be ``json`` or ``xml``)
108 ====================== =========================
110 The reply is a list of account names.
111 If a ``format=xml`` or ``format=json`` argument is given, extended information on the accounts will be returned, serialized in the chosen format.
112 For each account, the information will include the following (names will be in lower case and with hyphens replaced with underscores):
114 =========================== ============================
116 =========================== ============================
117 name The name of the account
118 last_modified The last account modification date (regardless of ``until``)
119 =========================== ============================
121 Example ``format=json`` reply:
125 [{"name": "user", "last_modified": "2011-07-19T10:48:16"}, ...]
127 Example ``format=xml`` reply:
131 <?xml version="1.0" encoding="UTF-8"?>
135 <last_modified>2011-07-19T10:48:16</last_modified>
137 <account>...</account>
140 =========================== =====================
141 Return Code Description
142 =========================== =====================
143 200 (OK) The request succeeded
144 204 (No Content) The user has no access to other accounts (only for non-extended replies)
145 =========================== =====================
147 Will use a ``200`` return code if the reply is of type json/xml.
154 ========= ==================
155 Operation Description
156 ========= ==================
157 HEAD Retrieve account metadata
159 POST Update account metadata
160 ========= ==================
165 ==================== ===========================
166 Request Header Name Value
167 ==================== ===========================
168 If-Modified-Since Retrieve if account has changed since provided timestamp
169 If-Unmodified-Since Retrieve if account has not changed since provided timestamp
170 ==================== ===========================
174 ====================== ===================================
175 Request Parameter Name Value
176 ====================== ===================================
177 until Optional timestamp
178 ====================== ===================================
180 Cross-user requests are not allowed to use ``until`` and only include the account modification date in the reply.
182 ========================== =====================
183 Reply Header Name Value
184 ========================== =====================
185 X-Account-Container-Count The total number of containers
186 X-Account-Object-Count The total number of objects (**TBD**)
187 X-Account-Bytes-Used The total number of bytes stored
188 X-Account-Bytes-Remaining The total number of bytes remaining (**TBD**)
189 X-Account-Last-Login The last login (**TBD**)
190 X-Account-Until-Timestamp The last account modification date until the timestamp provided
191 X-Account-Group-* Optional user defined groups
192 X-Account-Meta-* Optional user defined metadata
193 Last-Modified The last account modification date (regardless of ``until``)
194 ========================== =====================
198 ================ =====================
199 Return Code Description
200 ================ =====================
201 204 (No Content) The request succeeded
202 ================ =====================
208 ==================== ===========================
209 Request Header Name Value
210 ==================== ===========================
211 If-Modified-Since Retrieve if account has changed since provided timestamp
212 If-Unmodified-Since Retrieve if account has not changed since provided timestamp
213 ==================== ===========================
217 ====================== =========================
218 Request Parameter Name Value
219 ====================== =========================
220 limit The amount of results requested (default is 10000)
221 marker Return containers with name lexicographically after marker
222 format Optional extended reply type (can be ``json`` or ``xml``)
223 shared Show only shared containers (no value parameter)
224 until Optional timestamp
225 ====================== =========================
227 The reply is a list of container names. Account headers (as in a ``HEAD`` request) will also be included.
228 Cross-user requests are not allowed to use ``until`` and only include the account/container modification dates in the reply.
230 If a ``format=xml`` or ``format=json`` argument is given, extended information on the containers will be returned, serialized in the chosen format.
231 For each container, the information will include all container metadata (names will be in lower case and with hyphens replaced with underscores):
233 =========================== ============================
235 =========================== ============================
236 name The name of the container
237 count The number of objects inside the container
238 bytes The total size of the objects inside the container
239 last_modified The last container modification date (regardless of ``until``)
240 x_container_until_timestamp The last container modification date until the timestamp provided
241 x_container_policy_* Container behavior and limits
242 x_container_meta_* Optional user defined metadata
243 =========================== ============================
245 For examples of container details returned in JSON/XML formats refer to the OOS API documentation.
247 =========================== =====================
248 Return Code Description
249 =========================== =====================
250 200 (OK) The request succeeded
251 204 (No Content) The account has no containers (only for non-extended replies)
252 304 (Not Modified) The account has not been modified
253 412 (Precondition Failed) The condition set can not be satisfied
254 =========================== =====================
256 Will use a ``200`` return code if the reply is of type json/xml.
262 ==================== ===========================
263 Request Header Name Value
264 ==================== ===========================
265 X-Account-Group-* Optional user defined groups
266 X-Account-Meta-* Optional user defined metadata
267 ==================== ===========================
271 ====================== ============================================
272 Request Parameter Name Value
273 ====================== ============================================
274 update Do not replace metadata/groups (no value parameter)
275 ====================== ============================================
277 No reply content/headers.
279 The operation will overwrite all user defined metadata, except if ``update`` is defined.
280 To create a group, include an ``X-Account-Group-*`` header with the name in the key and a comma separated list of user names in the value. If no ``X-Account-Group-*`` header is present, no changes will be applied to groups. The ``update`` parameter also applies to groups. To delete a specific group, use ``update`` and an empty header value.
282 ================ ===============================
283 Return Code Description
284 ================ ===============================
285 202 (Accepted) The request has been accepted
286 ================ ===============================
294 ========= ============================
295 Operation Description
296 ========= ============================
297 HEAD Retrieve container metadata
299 PUT Create/update container
300 POST Update container metadata
301 DELETE Delete container
302 ========= ============================
308 ==================== ===========================
309 Request Header Name Value
310 ==================== ===========================
311 If-Modified-Since Retrieve if container has changed since provided timestamp
312 If-Unmodified-Since Retrieve if container has not changed since provided timestamp
313 ==================== ===========================
317 ====================== ===================================
318 Request Parameter Name Value
319 ====================== ===================================
320 until Optional timestamp
321 ====================== ===================================
323 Cross-user requests are not allowed to use ``until`` and only include the container modification date in the reply.
325 =========================== ===============================
326 Reply Header Name Value
327 =========================== ===============================
328 X-Container-Object-Count The total number of objects in the container
329 X-Container-Bytes-Used The total number of bytes of all objects stored
330 X-Container-Block-Size The block size used by the storage backend
331 X-Container-Block-Hash The hash algorithm used for block identifiers in object hashmaps
332 X-Container-Until-Timestamp The last container modification date until the timestamp provided
333 X-Container-Object-Meta A list with all meta keys used by objects
334 X-Container-Policy-* Container behavior and limits
335 X-Container-Meta-* Optional user defined metadata
336 Last-Modified The last container modification date (regardless of ``until``)
337 =========================== ===============================
339 The keys returned in ``X-Container-Object-Meta`` are all the unique strings after the ``X-Object-Meta-`` prefix, formatted as a comma-separated list. See container ``PUT`` for a reference of policy directives.
341 ================ ===============================
342 Return Code Description
343 ================ ===============================
344 204 (No Content) The request succeeded
345 ================ ===============================
351 ==================== ===========================
352 Request Header Name Value
353 ==================== ===========================
354 If-Modified-Since Retrieve if container has changed since provided timestamp
355 If-Unmodified-Since Retrieve if container has not changed since provided timestamp
356 ==================== ===========================
360 ====================== ===================================
361 Request Parameter Name Value
362 ====================== ===================================
363 limit The amount of results requested (default is 10000)
364 marker Return containers with name lexicographically after marker
365 prefix Return objects starting with prefix
366 delimiter Return objects up to the delimiter (discussion follows)
367 path Assume ``prefix=path`` and ``delimiter=/``
368 format Optional extended reply type (can be ``json`` or ``xml``)
369 meta Return objects having the specified meta keys (can be a comma separated list)
370 shared Show only shared objects (no value parameter)
371 until Optional timestamp
372 ====================== ===================================
374 The ``path`` parameter overrides ``prefix`` and ``delimiter``. When using ``path``, results will include objects ending in ``delimiter``.
376 The keys given with ``meta`` will be matched with the strings after the ``X-Object-Meta-`` prefix.
378 The reply is a list of object names. Container headers (as in a ``HEAD`` request) will also be included.
379 Cross-user requests are not allowed to use ``until`` and include the following limited set of headers in the reply:
381 =========================== ===============================
382 Reply Header Name Value
383 =========================== ===============================
384 X-Container-Block-Size The block size used by the storage backend
385 X-Container-Block-Hash The hash algorithm used for block identifiers in object hashmaps
386 X-Container-Object-Meta A list with all meta keys used by allowed objects (**TBD**)
387 Last-Modified The last container modification date
388 =========================== ===============================
390 If a ``format=xml`` or ``format=json`` argument is given, extended information on the objects will be returned, serialized in the chosen format.
391 For each object, the information will include all object metadata (names will be in lower case and with hyphens replaced with underscores):
393 ========================== ======================================
395 ========================== ======================================
396 name The name of the object
397 hash The ETag of the object
398 bytes The size of the object
399 content_type The MIME content type of the object
400 content_encoding The encoding of the object (optional)
401 content-disposition The presentation style of the object (optional)
402 last_modified The last object modification date (regardless of version)
403 x_object_version The object's version identifier
404 x_object_version_timestamp The object's version timestamp
405 x_object_modified_by The user that committed the object's version
406 x_object_manifest Object parts prefix in ``<container>/<object>`` form (optional)
407 x_object_sharing Object permissions (optional)
408 x_object_shared_by Object inheriting permissions (optional)
409 x_object_public Object's publicly accessible URI (optional)
410 x_object_meta_* Optional user defined metadata
411 ========================== ======================================
413 Extended replies may also include virtual directory markers in separate sections of the ``json`` or ``xml`` results.
414 Virtual directory markers are only included when ``delimiter`` is explicitly set. They correspond to the substrings up to and including the first occurrence of the delimiter.
415 In JSON results they appear as dictionaries with only a ``"subdir"`` key. In XML results they appear interleaved with ``<object>`` tags as ``<subdir name="..." />``.
416 In case there is an object with the same name as a virtual directory marker, the object will be returned.
418 For examples of object details returned in JSON/XML formats refer to the OOS API documentation.
420 =========================== ===============================
421 Return Code Description
422 =========================== ===============================
423 200 (OK) The request succeeded
424 204 (No Content) The account has no containers (only for non-extended replies)
425 304 (Not Modified) The container has not been modified
426 412 (Precondition Failed) The condition set can not be satisfied
427 =========================== ===============================
429 Will use a ``200`` return code if the reply is of type json/xml.
435 ==================== ================================
436 Request Header Name Value
437 ==================== ================================
438 X-Container-Policy-* Container behavior and limits
439 X-Container-Meta-* Optional user defined metadata
440 ==================== ================================
442 No reply content/headers.
444 If no policy is defined, the container will be created with the default values.
445 Available policy directives:
447 * ``versioning``: Set to ``auto``, ``manual`` or ``none`` (default is ``manual``)
448 * ``quota``: Size limit in KB (default is ``0`` - unlimited)
450 ================ ===============================
451 Return Code Description
452 ================ ===============================
453 201 (Created) The container has been created
454 202 (Accepted) The request has been accepted
455 ================ ===============================
461 ==================== ================================
462 Request Header Name Value
463 ==================== ================================
464 X-Container-Policy-* Container behavior and limits
465 X-Container-Meta-* Optional user defined metadata
466 ==================== ================================
470 ====================== ============================================
471 Request Parameter Name Value
472 ====================== ============================================
473 update Do not replace metadata/policy (no value parameter)
474 ====================== ============================================
476 No reply content/headers.
478 The operation will overwrite all user defined metadata, except if ``update`` is defined.
479 To change policy, include an ``X-Container-Policy-*`` header with the name in the key. If no ``X-Container-Policy-*`` header is present, no changes will be applied to policy. The ``update`` parameter also applies to policy - deleted values will revert to defaults. To delete/revert a specific policy directive, use ``update`` and an empty header value. See container ``PUT`` for a reference of policy directives.
481 ================ ===============================
482 Return Code Description
483 ================ ===============================
484 202 (Accepted) The request has been accepted
485 ================ ===============================
491 ====================== ===================================
492 Request Parameter Name Value
493 ====================== ===================================
494 until Optional timestamp
495 ====================== ===================================
497 If ``until`` is defined, the container is "purged" up to that time (the history of all objects up to then is deleted).
499 No reply content/headers.
501 ================ ===============================
502 Return Code Description
503 ================ ===============================
504 204 (No Content) The request succeeded
505 409 (Conflict) The container is not empty
506 ================ ===============================
514 ========= =================================
515 Operation Description
516 ========= =================================
517 HEAD Retrieve object metadata
519 PUT Write object data or copy/move object
522 POST Update object metadata/data
524 ========= =================================
530 ==================== ================================
531 Request Header Name Value
532 ==================== ================================
533 If-Match Retrieve if ETags match
534 If-None-Match Retrieve if ETags don't match
535 If-Modified-Since Retrieve if object has changed since provided timestamp
536 If-Unmodified-Since Retrieve if object has not changed since provided timestamp
537 ==================== ================================
541 ====================== ===================================
542 Request Parameter Name Value
543 ====================== ===================================
544 version Optional version identifier
545 ====================== ===================================
549 ========================== ===============================
550 Reply Header Name Value
551 ========================== ===============================
552 ETag The ETag of the object
553 Content-Length The size of the object
554 Content-Type The MIME content type of the object
555 Last-Modified The last object modification date (regardless of version)
556 Content-Encoding The encoding of the object (optional)
557 Content-Disposition The presentation style of the object (optional)
558 X-Object-Version The object's version identifier
559 X-Object-Version-Timestamp The object's version timestamp
560 X-Object-Modified-By The user that comitted the object's version
561 X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional)
562 X-Object-Sharing Object permissions (optional)
563 X-Object-Shared-By Object inheriting permissions (optional)
564 X-Object-Public Object's publicly accessible URI (optional)
565 X-Object-Meta-* Optional user defined metadata
566 ========================== ===============================
570 ================ ===============================
571 Return Code Description
572 ================ ===============================
573 200 (No Content) The request succeeded
574 ================ ===============================
580 ==================== ================================
581 Request Header Name Value
582 ==================== ================================
583 Range Optional range of data to retrieve
584 If-Range Retrieve the missing part if entity is unchanged; otherwise, retrieve the entire new entity (used together with Range header)
585 If-Match Retrieve if ETags match
586 If-None-Match Retrieve if ETags don't match
587 If-Modified-Since Retrieve if object has changed since provided timestamp
588 If-Unmodified-Since Retrieve if object has not changed since provided timestamp
589 ==================== ================================
593 ====================== ===================================
594 Request Parameter Name Value
595 ====================== ===================================
596 format Optional extended reply type (can be ``json`` or ``xml``)
597 version Optional version identifier or ``list`` (specify a format if requesting a list)
598 ====================== ===================================
600 The reply is the object's data (or part of it), except if a hashmap is requested with the ``format`` parameter, or a version list with ``version=list`` (in which case an extended reply format must be specified). Object headers (as in a ``HEAD`` request) are always included.
602 Hashmaps expose the underlying storage format of the object. Note that each hash is computed after trimming trailing null bytes of the corresponding block.
604 Example ``format=json`` reply:
608 {"block_hash": "sha1", "hashes": ["7295c41da03d7f916440b98e32c4a2a39351546c", ...], "block_size": 131072, "bytes": 242}
610 Example ``format=xml`` reply:
614 <?xml version="1.0" encoding="UTF-8"?>
615 <object name="file" bytes="24223726" block_size="131072" block_hash="sha1">
616 <hash>7295c41da03d7f916440b98e32c4a2a39351546c</hash>
620 Version lists include the version identifier and timestamp for each available object version. Version identifiers can be arbitrary strings, so use the timestamp to find newer versions.
622 Example ``format=json`` reply:
626 {"versions": [[23, 1307700892], [28, 1307700898], ...]}
628 Example ``format=xml`` reply:
632 <?xml version="1.0" encoding="UTF-8"?>
634 <version timestamp="1307700892">23</version>
635 <version timestamp="1307700898">28</version>
636 <version timestamp="...">...</version>
639 The ``Range`` header may include multiple ranges, as outlined in RFC2616. Then the ``Content-Type`` of the reply will be ``multipart/byteranges`` and each part will include a ``Content-Range`` header.
641 ========================== ===============================
642 Reply Header Name Value
643 ========================== ===============================
644 ETag The ETag of the object
645 Content-Length The size of the data returned
646 Content-Type The MIME content type of the object
647 Content-Range The range of data included (only on a single range request)
648 Last-Modified The last object modification date (regardless of version)
649 Content-Encoding The encoding of the object (optional)
650 Content-Disposition The presentation style of the object (optional)
651 X-Object-Version The object's version identifier
652 X-Object-Version-Timestamp The object's version timestamp
653 X-Object-Modified-By The user that comitted the object's version
654 X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional)
655 X-Object-Sharing Object permissions (optional)
656 X-Object-Shared-By Object inheriting permissions (optional)
657 X-Object-Public Object's publicly accessible URI (optional)
658 X-Object-Meta-* Optional user defined metadata
659 ========================== ===============================
663 =========================== ==============================
664 Return Code Description
665 =========================== ==============================
666 200 (OK) The request succeeded
667 206 (Partial Content) The range request succeeded
668 304 (Not Modified) The object has not been modified
669 412 (Precondition Failed) The condition set can not be satisfied
670 416 (Range Not Satisfiable) The requested range is out of limits
671 =========================== ==============================
677 ==================== ================================
678 Request Header Name Value
679 ==================== ================================
680 If-Match Put if ETags match with current object
681 If-None-Match Put if ETags don't match with current object
682 ETag The MD5 hash of the object (optional to check written data)
683 Content-Length The size of the data written
684 Content-Type The MIME content type of the object
685 Transfer-Encoding Set to ``chunked`` to specify incremental uploading (if used, ``Content-Length`` is ignored)
686 X-Copy-From The source path in the form ``/<container>/<object>``
687 X-Move-From The source path in the form ``/<container>/<object>``
688 X-Source-Version The source version to copy from
689 Content-Encoding The encoding of the object (optional)
690 Content-Disposition The presentation style of the object (optional)
691 X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional)
692 X-Object-Sharing Object permissions (optional)
693 X-Object-Public Object is publicly accessible (optional)
694 X-Object-Meta-* Optional user defined metadata
695 ==================== ================================
699 ====================== ===================================
700 Request Parameter Name Value
701 ====================== ===================================
702 format Optional extended request type (can be ``json``) to create the object by suppling its hashmap instead
703 ====================== ===================================
705 The request is the object's data (or part of it), except if a hashmap is provided with the ``format`` parameter. If format is used and all different parts are stored in the server, the object is created, otherwise the server returns Conflict (409) with the list of the missing parts.
707 Hashmaps expose the underlying storage format of the object.
709 Example ``format=json`` request:
713 {"block_hash": "sha1", "hashes": ["7295c41da03d7f916440b98e32c4a2a39351546c", ...], "block_size": 131072, "bytes": 242}
715 Example ``format=xml`` request:
719 <?xml version="1.0" encoding="UTF-8"?>
720 <object name="file" bytes="24223726" block_size="131072" block_hash="sha1">
721 <hash>7295c41da03d7f916440b98e32c4a2a39351546c</hash>
725 ========================== ===============================
726 Reply Header Name Value
727 ========================== ===============================
728 ETag The MD5 hash of the object (on create)
729 X-Object-Version The object's new version
730 ========================== ===============================
732 The ``X-Object-Sharing`` header may include either a ``read=...`` comma-separated user/group list, or a ``write=...`` comma-separated user/group list, or both separated by a semicolon (``;``). Groups are specified as ``<account>:<group>``. To publish the object, set ``X-Object-Public`` to ``true``. To unpublish, set to ``false``, or use an empty header value.
734 =========================== ==============================
735 Return Code Description
736 =========================== ==============================
737 201 (Created) The object has been created
738 409 (Conflict) The object can not be created from the provided hashmap, or there are conflicting permissions (a list of missing hashes, or a conflicting sharing path will be included in the reply - in JSON format)
739 411 (Length Required) Missing ``Content-Length`` or ``Content-Type`` in the request
740 422 (Unprocessable Entity) The MD5 checksum of the data written to the storage system does not match the (optionally) supplied ETag value
741 =========================== ==============================
747 ==================== ================================
748 Request Header Name Value
749 ==================== ================================
750 If-Match Proceed if ETags match with object
751 If-None-Match Proceed if ETags don't match with object
752 Destination The destination path in the form ``/<container>/<object>``
753 Content-Type The MIME content type of the object (optional)
754 Content-Encoding The encoding of the object (optional)
755 Content-Disposition The presentation style of the object (optional)
756 X-Source-Version The source version to copy from
757 X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional)
758 X-Object-Sharing Object permissions (optional)
759 X-Object-Public Object is publicly accessible (optional)
760 X-Object-Meta-* Optional user defined metadata
761 ==================== ================================
763 Refer to ``PUT``/``POST`` for a description of request headers. Metadata is also copied, updated with any values defined. Sharing/publishing options are not copied.
765 ========================== ===============================
766 Reply Header Name Value
767 ========================== ===============================
768 X-Object-Version The object's new version
769 ========================== ===============================
773 =========================== ==============================
774 Return Code Description
775 =========================== ==============================
776 201 (Created) The object has been created
777 409 (Conflict) There are conflicting permissions (a conflicting sharing path will be included in the reply - in JSON format)
778 =========================== ==============================
784 Same as ``COPY``, without the ``X-Source-Version`` request header. The ``MOVE`` operation is always applied on the latest version.
790 ==================== ================================
791 Request Header Name Value
792 ==================== ================================
793 If-Match Proceed if ETags match with object
794 If-None-Match Proceed if ETags don't match with object
795 Content-Length The size of the data written (optional, to update)
796 Content-Type The MIME content type of the object (optional, to update)
797 Content-Range The range of data supplied (optional, to update)
798 Transfer-Encoding Set to ``chunked`` to specify incremental uploading (if used, ``Content-Length`` is ignored)
799 Content-Encoding The encoding of the object (optional)
800 Content-Disposition The presentation style of the object (optional)
801 X-Source-Object Update with data from the object at path ``/<container>/<object>`` (optional, to update)
802 X-Source-Version The source version to update from (optional, to update)
803 X-Object-Bytes The updated object's final size (optional, when updating)
804 X-Object-Manifest Object parts prefix in ``<container>/<object>`` form (optional)
805 X-Object-Sharing Object permissions (optional)
806 X-Object-Public Object is publicly accessible (optional)
807 X-Object-Meta-* Optional user defined metadata
808 ==================== ================================
812 ====================== ============================================
813 Request Parameter Name Value
814 ====================== ============================================
815 update Do not replace metadata (no value parameter)
816 ====================== ============================================
818 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.
820 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.
822 To update an object's data:
824 * Either set ``Content-Type`` to ``application/octet-stream``, or provide an object with ``X-Source-Object``. If ``Content-Type`` has some other value, it will be ignored and only the metadata will be updated.
825 * If the data is supplied in the request (using ``Content-Type`` instead of ``X-Source-Object``), a valid ``Content-Length`` header is required - except if using chunked transfers (set ``Transfer-Encoding`` to ``chunked``).
826 * Set ``Content-Range`` as specified in RFC2616, with the following differences:
828 * Client software MAY omit ``last-byte-pos`` of if the length of the range being transferred is unknown or difficult to determine.
829 * Client software SHOULD not specify the ``instance-length`` (use a ``*``), unless there is a reason for performing a size check at the server.
830 * If ``Content-Range`` used has a ``byte-range-resp-spec = *``, data will be appended to the object.
832 Optionally, truncate the updated object to the desired length with the ``X-Object-Bytes`` header.
834 A data update will trigger an ETag change. Updated ETags correspond to the single Merkle hash of the object's hashmap (refer to http://bittorrent.org/beps/bep_0030.html for more information).
836 No reply content. No reply headers if only metadata is updated.
838 ========================== ===============================
839 Reply Header Name Value
840 ========================== ===============================
841 ETag The new ETag of the object (data updated)
842 X-Object-Version The object's new version
843 ========================== ===============================
847 =========================== ==============================
848 Return Code Description
849 =========================== ==============================
850 202 (Accepted) The request has been accepted (not a data update)
851 204 (No Content) The request succeeded (data updated)
852 409 (Conflict) There are conflicting permissions (a conflicting sharing path will be included in the reply - in JSON format)
853 411 (Length Required) Missing ``Content-Length`` in the request
854 416 (Range Not Satisfiable) The supplied range is invalid
855 =========================== ==============================
857 The ``POST`` method can also be used for creating an object via a standard HTML form. If the request ``Content-Type`` is ``multipart/form-data``, none of the above headers will be processed. The form should have exactly two fields, as in the following example. ::
859 <form method="post" action="https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt" enctype="multipart/form-data">
860 <input type="hidden" name="X-Auth-Token" value="0000">
861 <input type="file" name="X-Object-Data">
862 <input type="submit">
865 This will create/override the object with the given name, as if using ``PUT``. The ``Content-Type`` of the object will be set to the value of the corresponding header sent in the part of the request containing the data. Metadata, sharing and other object attributes can not be set this way.
867 ========================== ===============================
868 Reply Header Name Value
869 ========================== ===============================
870 ETag The MD5 hash of the object
871 X-Object-Version The object's new version
872 ========================== ===============================
876 =========================== ==============================
877 Return Code Description
878 =========================== ==============================
879 201 (Created) The object has been created
880 =========================== ==============================
886 ====================== ===================================
887 Request Parameter Name Value
888 ====================== ===================================
889 until Optional timestamp
890 ====================== ===================================
892 If ``until`` is defined, the object is "purged" up to that time (the history up to then is deleted).
894 No reply content/headers.
896 =========================== ==============================
897 Return Code Description
898 =========================== ==============================
899 204 (No Content) The request succeeded
900 =========================== ==============================
902 Sharing and Public Objects
903 ^^^^^^^^^^^^^^^^^^^^^^^^^^
905 Read and write control in Pithos is managed by setting appropriate permissions with the ``X-Object-Sharing`` header. The permissions are applied using prefix-based inheritance. Thus, each set of authorization directives is applied to all objects sharing the same prefix with the object where the corresponding ``X-Object-Sharing`` header is defined. For simplicity, nested/overlapping permissions are not allowed. Setting ``X-Object-Sharing`` will fail, if the object is already "covered", or another object with a longer common-prefix name already has permissions. When retrieving an object, the ``X-Object-Shared-By`` header reports where it gets its permissions from. If not present, the object is the actual source of authorization directives.
907 A user may ``GET`` another account or container. The result will include a limited reply, containing only the allowed containers or objects respectively. A top-level request with an authentication token, will return a list of allowed accounts, so the user can easily find out which other users share objects.
909 Objects that are marked as public, via the ``X-Object-Public`` meta, are also available at the corresponding URI returned for ``HEAD`` or ``GET``. Requests for public objects do not need to include an ``X-Auth-Token``. Pithos will ignore request parameters and only include the following headers in the reply (all ``X-Object-*`` meta is hidden):
911 ========================== ===============================
912 Reply Header Name Value
913 ========================== ===============================
914 ETag The ETag of the object
915 Content-Length The size of the data returned
916 Content-Type The MIME content type of the object
917 Content-Range The range of data included (only on a single range request)
918 Last-Modified The last object modification date (regardless of version)
919 Content-Encoding The encoding of the object (optional)
920 Content-Disposition The presentation style of the object (optional)
921 ========================== ===============================
923 Public objects are not included and do not influence cross-user listings. They are, however, readable by all users.
928 List of differences from the OOS API:
930 * Support for ``X-Account-Meta-*`` style headers at the account level. Use ``POST`` to update.
931 * Support for ``X-Container-Meta-*`` style headers at the container level. Can be set when creating via ``PUT``. Use ``POST`` to update.
932 * Header ``X-Container-Object-Meta`` at the container level and parameter ``meta`` in container listings.
933 * Container policies to manage behavior and limits.
934 * Headers ``X-Container-Block-*`` at the container level, exposing the underlying storage characteristics.
935 * All metadata replies, at all levels, include latest modification information.
936 * At all levels, a ``HEAD`` or ``GET`` request may use ``If-Modified-Since`` and ``If-Unmodified-Since`` headers.
937 * 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.
938 * Option to include only shared containers/objects in listings.
939 * 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.
940 * Multi-range object ``GET`` support as outlined in RFC2616.
941 * Object hashmap retrieval through ``GET`` and the ``format`` parameter.
942 * Object create via hashmap through ``PUT`` and the ``format`` parameter.
943 * Object create using ``POST`` to support standard HTML forms.
944 * 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``. New ETag corresponds to the Merkle hash of the object's hashmap.
945 * Include new version identifier in replies for object replace/change requests.
946 * Object ``MOVE`` support.
947 * Conditional object create/update operations, using ``If-Match`` and ``If-None-Match`` headers.
948 * Time-variant account/container listings via the ``until`` parameter.
949 * Object versions - parameter ``version`` in ``HEAD``/``GET`` (list versions with ``GET``), ``X-Object-Version-*`` meta in replies, ``X-Source-Version`` in ``PUT``/``COPY``.
950 * 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.
951 * Support for prefix-based inheritance when enforcing permissions. Parent object carrying the authorization directives is reported in ``X-Object-Shared-By``.
952 * Large object support with ``X-Object-Manifest``.
953 * Trace the user that created/modified an object with ``X-Object-Modified-By``.
954 * Purge container/object history with the ``until`` parameter in ``DELETE``.
956 Clarifications/suggestions:
958 * Authentication is done by another system. The token is used in the same way, but it is obtained differently. The top level ``GET`` request is kept compatible with the OOS API and allows for guest/testing operations.
959 * Some processing is done in the variable part of all ``X-*-Meta-*`` headers. If it includes underscores, they will be converted to dashes and the first letter of all intra-dash strings will be capitalized.
960 * A ``GET`` reply for a level will include all headers of the corresponding ``HEAD`` request.
961 * To avoid conflicts between objects and virtual directory markers in container listings, it is recommended that object names do not end with the delimiter used.
962 * The ``Accept`` header may be used in requests instead of the ``format`` parameter to specify the desired reply format. The parameter overrides the header (**TBD**).
963 * Container/object lists use a ``200`` return code if the reply is of type json/xml. The reply will include an empty json/xml.
964 * In headers, dates are formatted according to RFC 1123. In extended information listings, the ``last_modified`` field is formatted according to ISO 8601 (for OOS API compatibility). All other fields (Pithos extensions) use integer tiemstamps.
965 * 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.
966 * A copy/move using ``PUT``/``COPY``/``MOVE`` will always update metadata, keeping all old values except the ones redefined in the request headers.
967 * 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.
975 Hopefully this API will allow for a multitude of client implementations, each supporting a different device or operating system. All clients will be able to manipulate containers and objects - even software only designed for OOS API compatibility. But a Pithos interface should not be only about showing containers and folders. There are some extra user interface elements and functionalities that should be common to all implementations.
977 Upon entrance to the service, a user is presented with the following elements - which can be represented as folders or with other related icons:
979 * The ``home`` element, which is used as the default entry point to the user's "files". Objects under ``home`` are represented in the usual hierarchical organization of folders and files.
980 * The ``trash`` element, which contains files that have been marked for deletion, but can still be recovered.
981 * The ``shared`` element, which contains all objects shared by the user to other users of the system.
982 * The ``others`` element, which contains all objects that other users share with the user.
983 * The ``tags`` element, which lists the names of tags the user has defined. This can be an entry point to list all files that have been assigned a specific tag or manage tags in general (remove a tag completely, rename a tag etc.).
984 * The ``groups`` element, which contains the names of groups the user has defined. Each group consists of a user list. Group creation, deletion, and manipulation is carried out by actions originating here.
985 * The ``history`` element, which allows browsing past instances of ``home`` and - optionally - ``trash``.
987 Objects in Pithos can be:
989 * Assigned custom tags.
990 * Moved to trash and then deleted.
991 * Shared with specific permissions.
992 * Made public (shared with non-Pithos users).
993 * Restored from previous versions.
995 Some of these functions are performed by the client software and some by the Pithos server.
997 Implementation Guidelines
998 ^^^^^^^^^^^^^^^^^^^^^^^^^
1000 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.
1002 Object names should use the ``/`` delimiter to impose a hierarchy of folders and files.
1004 The ``shared`` element should be implemented as a read-only view of the ``pithos`` container, using the ``shared`` parameter when listing objects. The ``others`` element, should start with a top-level ``GET`` to retrieve the list of accounts accessible to the user. It is suggested that the client software hides the next step of navigation - the container - if it only includes ``pithos`` and forwards the user directly to the objects.
1006 Public objects are not included in ``shared`` and ``others`` listings. It is suggested that they are marked in a visually distinctive way in ``pithos`` listings (for example using an icon overlay).
1008 At the object level, tags are implemented by managing metadata keys. The client software should allow the user to use any string as a tag and set the corresponding ``X-Object-Meta-<tag>`` key at the server. The API extensions provided, allow for listing all tags in a container and filtering object listings based on one or more tags. The tag list is sufficient for implementing the ``tags`` element, either as a special, virtual folder (as done in the first version of Pithos), or as an application menu.
1010 A special application menu, or a section in application preferences, should be devoted to managing groups (the ``groups`` element). All group-related actions are implemented at the account level.
1012 Browsing past versions of objects should be available both at the object and the container level. At the object level, a list of past versions can be included in the screen showing details or more information on the object (metadata, tags, permissions, etc.). At the container level, it is suggested that clients use a ``history`` element, which presents to the user a read-only, time-variable view of ``pithos`` contents. This can be accomplished via the ``until`` parameter in listings. Optionally, ``history`` may include ``trash``.
1014 Recommended Practices and Examples
1015 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1017 Assuming an authentication token is obtained (**TBD**), the following high-level operations are available - shown with ``curl``:
1019 * Get account information ::
1022 -H "X-Auth-Token: 0000" \
1023 https://pithos.dev.grnet.gr/v1/user
1025 * List available containers ::
1028 -H "X-Auth-Token: 0000" \
1029 https://pithos.dev.grnet.gr/v1/user
1031 * Get container information ::
1034 -H "X-Auth-Token: 0000" \
1035 https://pithos.dev.grnet.gr/v1/user/pithos
1037 * Add a new container ::
1040 -H "X-Auth-Token: 0000" \
1041 https://pithos.dev.grnet.gr/v1/user/test
1043 * Delete a container ::
1045 curl -X DELETE -D - \
1046 -H "X-Auth-Token: 0000" \
1047 https://pithos.dev.grnet.gr/v1/user/test
1049 * List objects in a container ::
1052 -H "X-Auth-Token: 0000" \
1053 https://pithos.dev.grnet.gr/v1/user/pithos
1055 * List objects in a container (extended reply) ::
1058 -H "X-Auth-Token: 0000" \
1059 https://pithos.dev.grnet.gr/v1/user/pithos?format=json
1061 It is recommended that extended replies are cached and subsequent requests utilize the ``If-Modified-Since`` header.
1063 * List metadata keys used by objects in a container
1065 Will be in the ``X-Container-Object-Meta`` reply header, included in container information or object list (``HEAD`` or ``GET``).
1067 * List objects in a container having a specific meta defined ::
1070 -H "X-Auth-Token: 0000" \
1071 https://pithos.dev.grnet.gr/v1/user/pithos?meta=favorites
1073 * Retrieve an object ::
1076 -H "X-Auth-Token: 0000" \
1077 https://pithos.dev.grnet.gr/v1/user/pithos/README.txt
1079 * Retrieve an object (specific ranges of data) ::
1082 -H "X-Auth-Token: 0000" \
1083 -H "Range: bytes=0-9" \
1084 https://pithos.dev.grnet.gr/v1/user/pithos/README.txt
1086 This will return the first 10 bytes. To get the first 10, bytes 30-39 and the last 100 use ``Range: bytes=0-9,30-39,-100``.
1088 * Add a new object (folder type) (**TBD**) ::
1091 -H "X-Auth-Token: 0000" \
1092 -H "Content-Type: application/folder" \
1093 https://pithos.dev.grnet.gr/v1/user/pithos/folder
1095 * Add a new object ::
1098 -H "X-Auth-Token: 0000" \
1099 -H "Content-Type: text/plain" \
1101 https://pithos.dev.grnet.gr/v1/user/pithos/folder/EXAMPLE.txt
1103 * Update an object ::
1106 -H "X-Auth-Token: 0000" \
1107 -H "Content-Length: 10" \
1108 -H "Content-Type: application/octet-stream" \
1109 -H "Content-Range: bytes 10-19/*" \
1111 https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
1113 This will update bytes 10-19 with the data specified.
1115 * Update an object (append) ::
1118 -H "X-Auth-Token: 0000" \
1119 -H "Content-Length: 10" \
1120 -H "Content-Type: application/octet-stream" \
1121 -H "Content-Range: bytes */*" \
1123 https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
1125 * Update an object (truncate) ::
1128 -H "X-Auth-Token: 0000" \
1129 -H "X-Source-Object: /folder/EXAMPLE.txt" \
1130 -H "Content-Range: bytes 0-0/*" \
1131 -H "X-Object-Bytes: 0" \
1132 https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
1134 This will truncate the object to 0 bytes.
1136 * Add object metadata ::
1139 -H "X-Auth-Token: 0000" \
1140 -H "X-Object-Meta-First: first_meta_value" \
1141 -H "X-Object-Meta-Second: second_meta_value" \
1142 https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
1144 * Delete object metadata ::
1147 -H "X-Auth-Token: 0000" \
1148 -H "X-Object-Meta-First: first_meta_value" \
1149 https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
1151 Metadata can only be "set". To delete ``X-Object-Meta-Second``, reset all metadata.
1153 * Delete an object ::
1155 curl -X DELETE -D - \
1156 -H "X-Auth-Token: 0000" \
1157 https://pithos.dev.grnet.gr/v1/user/folder/EXAMPLE.txt
projects / pithos / blob